refactor(api): Extract StageDefinitionBuilder and supporting classes (s…

…pinnaker#3490)

* chore(core): Expose orca-api as api dependency

* refactor(core): Rename Execution to PipelineExecution

* refactor(plugins): Rename Stage to StageExecution

* refactor(plugins): Rename Task to TaskExecution

* refactor(plugins): Move SimpleStage extension point to new package

* refactor(plugins): Extracting ExecutionType out of PipelineExecution

* feat(plugins): Add StageExecution api

* feat(plugins): Add TaskExecutino api

* refactor(plugins): Move ExecutionStatus to orca-api

* refactor(plugins): Move TaskResult to orca-api

* refactor(plugins): Move SyntheticStageOwner to orca-api

* refactor(plugins): Rename Pipeline, Stage, TaskExecution models to *Impl

* refactor(plugins): Change signatures of TaskExecutionImpl to TaskExecution

* refactor(plugins): Move Trigger to orca-api

* refactor(plugins): Migrate codebase to use PipelineExecution and StageExecution interfaces

* refactor(plugins): Move Task to orca-api

* refactor(plugins): Move RetryableTask to orca-api

* refactor(plugins): Move CancellableStage to orca-api

* chore(plugins): Note about AuthenticatedStage refactor

* refactor(plugins): Remove internals-only methods from StageDefinitionBuilder

* refactor(plugins): Move StageDefinitionBuilder to orca-api

* refactor(plugins): Move api interfaces and classes to new packages

* docs(plugins): Adding dokka to orca-api

* docs(plugins): Some api docs

* feat(plugins): Make StageDefinitionBuilder an extension point

* refactor(plugins): Fix failing tests from 1.5w rebase

* fix(canary): Groovyism missing an import but compiling fine

build.gradle

@@ -30,6 +30,7 @@ buildscript {
     }
     classpath "com.netflix.nebula:nebula-kotlin-plugin:1.3.31"
     classpath "org.jetbrains.kotlin:kotlin-allopen:1.3.31"
+    classpath "org.jetbrains.dokka:dokka-gradle-plugin:0.10.1"
   }
 }
 

orca-core/src/main/java/com/netflix/spinnaker/orca/pipeline/model/SourceCodeTrigger.kt → gradle/dokka.gradle

@@ -14,15 +14,13 @@
  * limitations under the License.
  */
 
-package com.netflix.spinnaker.orca.pipeline.model
+apply plugin: "org.jetbrains.dokka"
 
-/**
- * Defines properties that are common across different types of source code triggers.
- */
-interface SourceCodeTrigger : Trigger {
-  val source: String
-  val project: String
-  val branch: String
-  val slug: String
-  val hash: String
+dokka {
+  outputFormat = 'html'
+  outputDirectory = "$buildDir/dokka"
+
+  configuration {
+    jdkVersion = 8
+  }
 }

gradle/wrapper/gradle-wrapper.properties

@@ -1,5 +1,6 @@
+#Wed Mar 04 00:10:14 PST 2020
+distributionUrl=https\://services.gradle.org/distributions/gradle-5.5.1-all.zip
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-5.5.1-bin.zip
-zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
+zipStoreBase=GRADLE_USER_HOME

orca-api/api.md

@@ -0,0 +1,3 @@
+# Module orca-api
+
+I need to say something about things here.

orca-api/orca-api.gradle

@@ -15,20 +15,28 @@
  */
 
 apply from: "$rootDir/gradle/kotlin.gradle"
+apply from: "$rootDir/gradle/dokka.gradle"
 apply from: "$rootDir/gradle/spock.gradle"
 
-test {
-  useJUnitPlatform {
-    includeEngines "junit-vintage", "junit-jupiter"
-  }
-}
-
 dependencies {
-  api "com.netflix.spinnaker.kork:kork-plugins-api"
+  api("com.netflix.spinnaker.kork:kork-plugins-api")
+  api("com.netflix.spinnaker.kork:kork-artifacts")
 
   compileOnly("org.projectlombok:lombok")
   annotationProcessor("org.projectlombok:lombok")
 
   testRuntimeOnly("org.junit.jupiter:junit-jupiter-api")
   testRuntimeOnly("org.junit.vintage:junit-vintage-engine")
 }
+
+test {
+  useJUnitPlatform {
+    includeEngines "junit-vintage", "junit-jupiter"
+  }
+}
+
+dokka {
+  configuration {
+    includes = ["api.md"]
+  }
+}

orca-api/src/main/java/com/netflix/spinnaker/orca/api/annotations/Immutable.java

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2020 Netflix, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+package com.netflix.spinnaker.orca.api.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Target;
+
+/**
+ * Signals that the annotated element is an immutable object. Write operations against this element
+ * will fail.
+ */
+@Target({ElementType.FIELD, ElementType.LOCAL_VARIABLE, ElementType.PARAMETER, ElementType.METHOD})
+public @interface Immutable {}

orca-core/src/main/java/com/netflix/spinnaker/orca/CancellableStage.java → orca-api/src/main/java/com/netflix/spinnaker/orca/api/pipeline/CancellableStage.java

@@ -1,31 +1,34 @@
 /*
- * Copyright 2017 Netflix, Inc.
+ * Copyright 2020 Netflix, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
- *     http://www.apache.org/licenses/LICENSE-2.0
+ *   http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package com.netflix.spinnaker.orca;
+package com.netflix.spinnaker.orca.api.pipeline;
 
-import com.netflix.spinnaker.orca.pipeline.model.Stage;
+import com.netflix.spinnaker.kork.annotations.Beta;
+import com.netflix.spinnaker.orca.api.pipeline.models.StageExecution;
 import java.util.Map;
 
+/** A stage that is capable of being cancelled. */
+@Beta
 public interface CancellableStage {
-  Result cancel(Stage stage);
+  Result cancel(StageExecution stage);
 
   class Result {
     private final String stageId;
     private final Map details;
 
-    public Result(Stage stage, Map details) {
+    public Result(StageExecution stage, Map details) {
       this.stageId = stage.getId();
       this.details = details;
     }

orca-core/src/main/java/com/netflix/spinnaker/orca/OverridableTimeoutRetryableTask.java → orca-api/src/main/java/com/netflix/spinnaker/orca/api/pipeline/OverridableTimeoutRetryableTask.java

@@ -1,24 +1,29 @@
 /*
- * Copyright 2017 Netflix, Inc.
+ * Copyright 2020 Netflix, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
- *     http://www.apache.org/licenses/LICENSE-2.0
+ *   http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package com.netflix.spinnaker.orca;
+package com.netflix.spinnaker.orca.api.pipeline;
+
+import com.netflix.spinnaker.kork.annotations.Alpha;
 
 /**
  * A retryable task whose timeout is taken from the top level stage if that value has been
  * overridden.
  *
  * <p>These are typically wait/monitor stages
+ *
+ * <p>TODO(rz): What even is the point of this interface?
  */
+@Alpha
 public interface OverridableTimeoutRetryableTask extends RetryableTask {}

orca-core/src/main/java/com/netflix/spinnaker/orca/RetryableTask.java → orca-api/src/main/java/com/netflix/spinnaker/orca/api/pipeline/RetryableTask.java

@@ -1,41 +1,45 @@
 /*
- * Copyright 2017 Netflix, Inc.
+ * Copyright 2020 Netflix, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
- *     http://www.apache.org/licenses/LICENSE-2.0
+ *   http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package com.netflix.spinnaker.orca;
+package com.netflix.spinnaker.orca.api.pipeline;
 
-import com.netflix.spinnaker.orca.pipeline.model.Stage;
+import com.netflix.spinnaker.kork.annotations.Beta;
+import com.netflix.spinnaker.orca.api.pipeline.models.StageExecution;
 import java.time.Duration;
 
 /**
  * A retryable task defines its backoff period (the period between delays) and its timeout (the
  * total period of the task)
  */
+@Beta
 public interface RetryableTask extends Task {
+  /** TODO(rz): Use Duration. */
   long getBackoffPeriod();
 
+  /** TODO(rz): Use Duration. */
   long getTimeout();
 
-  default long getDynamicTimeout(Stage stage) {
+  default long getDynamicTimeout(StageExecution stage) {
     return getTimeout();
   }
 
   default long getDynamicBackoffPeriod(Duration taskDuration) {
     return getBackoffPeriod();
   }
 
-  default long getDynamicBackoffPeriod(Stage stage, Duration taskDuration) {
+  default long getDynamicBackoffPeriod(StageExecution stage, Duration taskDuration) {
     return getDynamicBackoffPeriod(taskDuration);
   }
 }

orca-core/src/main/java/com/netflix/spinnaker/orca/pipeline/model/SyntheticStageOwner.java → orca-api/src/main/java/com/netflix/spinnaker/orca/api/pipeline/SyntheticStageOwner.java

@@ -1,7 +1,7 @@
 /*
- * Copyright 2016 Netflix, Inc.
+ * Copyright 2020 Netflix, Inc.
  *
- * Licensed under the Apache License, Version 2.0 (the "License")
+ * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
@@ -12,9 +12,10 @@
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
+ *
  */
 
-package com.netflix.spinnaker.orca.pipeline.model;
+package com.netflix.spinnaker.orca.api.pipeline;
 
 public enum SyntheticStageOwner {
   STAGE_BEFORE,

orca-api/src/main/java/com/netflix/spinnaker/orca/api/pipeline/Task.java

@@ -0,0 +1,80 @@
+/*
+ * Copyright 2020 Netflix, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.netflix.spinnaker.orca.api.pipeline;
+
+import com.netflix.spinnaker.kork.annotations.Beta;
+import com.netflix.spinnaker.orca.api.pipeline.models.StageExecution;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.Collections;
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+
+/** A discrete unit of work in a pipeline execution that does one thing and one thing only. */
+@Beta
+public interface Task {
+  /**
+   * Execute the business logic of the task, using the provided stage execution state.
+   *
+   * @param stage The running stage execution stage
+   * @return The result of this Task's execution
+   */
+  @Nonnull
+  TaskResult execute(@Nonnull StageExecution stage);
+
+  /**
+   * Behavior to be called on Task timeout.
+   *
+   * <p>This method should be used if you need to perform any cleanup operations in response to the
+   * task being aborted after taking too long to complete.
+   *
+   * @param stage The running state execution state
+   * @return
+   */
+  default @Nullable TaskResult onTimeout(@Nonnull StageExecution stage) {
+    return null;
+  }
+
+  /**
+   * Behavior to be called on Task cancellation.
+   *
+   * <p>This method should be used if you need to perform cleanup in response to the task being
+   * cancelled before it was able to complete.
+   *
+   * @param stage The running state execution state
+   */
+  default void onCancel(@Nonnull StageExecution stage) {}
+
+  /** A collection of known aliases. */
+  default Collection<String> aliases() {
+    if (getClass().isAnnotationPresent(Aliases.class)) {
+      return Arrays.asList(getClass().getAnnotation(Aliases.class).value());
+    }
+
+    return Collections.emptyList();
+  }
+
+  /** Allows backwards compatibility of a task's "type", even through class renames / refactors. */
+  @Retention(RetentionPolicy.RUNTIME)
+  @Target(ElementType.TYPE)
+  @interface Aliases {
+    String[] value() default {};
+  }
+}