Inherit configuration from other buildpacks (#4)

* Support for inheriting Release Phase configuration from other buildpacks via Build Plan

* Improve docs

Author: mars

Cargo.lock

@@ -14,6 +14,7 @@ indoc = "2"
 release_artifacts = { path = "../../common/release_artifacts" }
 release_commands = { path = "../../common/release_commands" }
 tokio = { version = "1.40.0", features = ["macros", "rt-multi-thread"] }
+toml = { version = "0.8", features = ["preserve_order"] }
 
 [dev-dependencies]
 libcnb-test = "=0.22.0"

buildpacks/release-phase/Cargo.toml

@@ -14,18 +14,10 @@ schema-version = "0.2"
 uri = "heroku/release-phase"
 ```
 
-### Release Build command
-
-```toml
-[com.heroku.phase.release-build]
-command = "bash"
-args = ["-c", "npm build"]
-```
-
-This command must output release artifacts into `/workspace/static-artifacts/`. The content of this directory will be stored during Release Phase by the `RELEASE_ID`, and then automatically retrieved for `web` processes, during start-up.
-
 ### Release commands
 
+*Multiple `release` commands are supported as a TOML array, their entries declared by `[[…]]`.*
+
 ```toml
 [[com.heroku.phase.release]]
 command = "bash"
@@ -38,6 +30,18 @@ args = ["-c", "./bin/purge-cache"]
 
 These commands are ephemeral. No changes to the filesystem are persisted.
 
+### Release Build command
+
+*Only a single `release-build` command is supported. The entry must be declared with `[…]`.*
+
+```toml
+[com.heroku.phase.release-build]
+command = "bash"
+args = ["-c", "npm build"]
+```
+
+This command must output release artifacts into `/workspace/static-artifacts/`. The content of this directory will be stored during Release Phase by the `RELEASE_ID`, and then automatically retrieved for `web` processes, during start-up.
+
 ## Configuration: runtime environment vars
 
 ### `RELEASE_ID`
@@ -66,4 +70,52 @@ Artifacts are stored at the `STATIC_ARTIFACTS_URL` with the name `release-<RELEA
 
 **Required for `s3` URLs.** The access secret.
 
+## Inherited Configuration
+
+Other buildpacks can return a [Build Plan](https://github.com/buildpacks/spec/blob/main/buildpack.md#build-plan-toml) from `detect` for Release Phase configuration.
+
+The array of `release` commands defined in an app's `project.toml` and the inherited Build Plan are combined into a sequence:
+1. `release` commands inherited from the Build Plan
+2. `release` commands declared in `project.toml`.
+
+Only a single `release-build` command will be executed during Release Phase:
+* the `release-build` command declared in `project.toml` takes precedence
+* otherwise `release-build` inherited from Build Plan
+* if multiple Build Plan entries declare `release-build`, the last one takes precedence.
+
+This example sets a `release` & `release-build` commands in the build plan, using the supported [project configuration](#configuration-projecttoml):
 
+```toml
+[[requires]]
+name = "release-phase"
+
+[requires.metadata.release-build]
+command = "bash"
+args = ["-c", "npm run build"]
+source = "My Awesome Buildpack"
+
+[[requires.metadata.release]]
+command = "bash"
+args = ["-c", "echo 'Hello world!'"]
+source = "My Awesome Buildpack"
+```
+
+Example using [libcnb.rs](https://github.com/heroku/libcnb.rs):
+
+```rust
+fn detect(&self, context: DetectContext<Self>) -> libcnb::Result<DetectResult, Self::Error> {
+    let mut release_phase_req = Require::new("release-phase");
+    let _ = release_phase_req.metadata(toml! {
+        [release-build]
+        command = "bash"
+        args = ["-c", "npm run build"]
+        source = "My Awesome Buildpack"
+    });
+    let plan_builder = BuildPlanBuilder::new()
+        .requires(release_phase_req);
+
+    DetectResultBuilder::pass()
+        .build_plan(plan_builder.build())
+        .build()
+}
+```

buildpacks/release-phase/README.md

@@ -3,6 +3,7 @@ use commons_ruby::output::build_log::{BuildLog, Logger, StartedLogger};
 use commons_ruby::output::fmt;
 use commons_ruby::output::fmt::DEBUG_INFO;
 use indoc::formatdoc;
+use libcnb::TomlFileError;
 use std::fmt::Display;
 use std::io::stdout;
 
@@ -16,6 +17,7 @@ pub(crate) enum ReleasePhaseBuildpackError {
     CannotInstallArtifactLoader(std::io::Error),
     CannotInstallCommandExecutor(std::io::Error),
     CannotCreatWebExecD(std::io::Error),
+    CannotReadProjectToml(TomlFileError),
     ConfigurationFailed(release_commands::Error),
 }
 
@@ -59,6 +61,13 @@ fn on_buildpack_error(error: ReleasePhaseBuildpackError, logger: Box<dyn Started
                 Cannot create exec.d/web for {buildpack_name}
             ", buildpack_name = fmt::value(BUILDPACK_NAME) });
         }
+        ReleasePhaseBuildpackError::CannotReadProjectToml(error) => {
+            print_error_details(logger, &error)
+                .announce()
+                .error(&formatdoc! {"
+                Error reading project.toml for {buildpack_name}
+            ", buildpack_name = fmt::value(BUILDPACK_NAME) });
+        }
         ReleasePhaseBuildpackError::ConfigurationFailed(error) => {
             print_error_details(logger, &error)
                 .announce()

buildpacks/release-phase/src/errors.rs

@@ -3,6 +3,7 @@ mod setup_release_phase;
 
 use crate::errors::{on_error, ReleasePhaseBuildpackError};
 use libcnb::build::{BuildContext, BuildResult, BuildResultBuilder};
+use libcnb::data::build_plan::{BuildPlanBuilder, Require};
 use libcnb::data::launch::{LaunchBuilder, ProcessBuilder};
 use libcnb::data::process_type;
 use libcnb::detect::{DetectContext, DetectResult, DetectResultBuilder};
@@ -33,7 +34,13 @@ impl Buildpack for ReleasePhaseBuildpack {
     type Error = ReleasePhaseBuildpackError;
 
     fn detect(&self, _context: DetectContext<Self>) -> libcnb::Result<DetectResult, Self::Error> {
-        DetectResultBuilder::pass().build()
+        let plan_builder = BuildPlanBuilder::new()
+            .provides("release-phase")
+            .requires(Require::new("release-phase"));
+
+        DetectResultBuilder::pass()
+            .build_plan(plan_builder.build())
+            .build()
     }
 
     fn build(&self, context: BuildContext<Self>) -> libcnb::Result<BuildResult, Self::Error> {

buildpacks/release-phase/src/main.rs

@@ -1,20 +1,38 @@
 use std::fs;
 
 use crate::{ReleasePhaseBuildpack, ReleasePhaseBuildpackError};
-use libcnb::additional_buildpack_binary_path;
 use libcnb::data::layer_name;
 use libcnb::layer::LayerRef;
+use libcnb::{additional_buildpack_binary_path, read_toml_file};
 use libcnb::{build::BuildContext, layer::UncachedLayerDefinition};
 use libherokubuildpack::log::log_info;
 use release_commands::{generate_commands_config, write_commands_config};
+use toml::Table;
 
 pub(crate) fn setup_release_phase(
     context: &BuildContext<ReleasePhaseBuildpack>,
 ) -> Result<
     Option<LayerRef<ReleasePhaseBuildpack, (), ()>>,
     libcnb::Error<ReleasePhaseBuildpackError>,
 > {
-    let commands_config = generate_commands_config(&context.app_dir.join("project.toml"))
+    let project_toml_path = &context.app_dir.join("project.toml");
+    let project_toml = if project_toml_path.is_file() {
+        read_toml_file::<toml::Value>(project_toml_path)
+            .map_err(ReleasePhaseBuildpackError::CannotReadProjectToml)?
+    } else {
+        toml::Table::new().into()
+    };
+
+    // Load a table of Build Plan [requires.metadata] from context.
+    // When a key is defined multiple times, the last one wins.
+    let mut build_plan_config = Table::new();
+    context.buildpack_plan.entries.iter().for_each(|e| {
+        e.metadata.iter().for_each(|(k, v)| {
+            build_plan_config.insert(k.to_owned(), v.to_owned());
+        });
+    });
+
+    let commands_config = generate_commands_config(&project_toml, build_plan_config)
         .map_err(ReleasePhaseBuildpackError::ConfigurationFailed)?;
 
     if commands_config.release.is_none() && commands_config.release_build.is_none() {