Shared layer logic for consistent output and unit testing (#327)

* Let rust-analyzer reorder use statements

There was a newline preventing rust-analyzer from ordering the `use` statements. I removed it, and saved and this is the outcome.

* Move metadata diff logic into a shared trait

* Extract invalid_metadata_action to shared module

* Extract restored_layer_action to shared module

* Bundle default cache behavior into shared module

* Ensure we don't forget to write new metdata

* Apply clippy suggestion

* Add a test for metadata differences

* Handle case where metadata is invalid

It might be safe to `expect` in the specific case, but not in the general one. We can return a nicely formatted string with information if it ever happens.

* Assert desired caching behavior

Instead of asserting implementation (that diffing a metadata object returns a vec entry), assert the behavior we want (that it clears the cache).

* Clippy

* Use standardized output

* Add tests to shared layer cache logic

To fully exercise all caching logic in the shared folder, I'm introducing a helper to create a temporary `BuildContext` that can be used for exercising caching logic in test.

This also introduces tests for both `restored_layer_action` states as called through `cached_layer_write_metadata`. Which should address this comment #327 (comment).

* Assert the behavior of invalid_metadata_action

* Exercise same interface used in file

In the ruby_install_layer we're exercising `cached_layer_write_metadata` but we were testing `restored_layer_action` which is called currently but might not be in the future via refactoring. This change asserts the behavior we want while using the exact same interface we are currently using.

* Combine distro name and version in changed output

* Add helper for removing ANSI codes for testing

* Format distribution values as backticks with color

* Assert all difference output

- Ensures each of these cases where the vec is not empty will clear the cache.
- Makes it easier for reviewers to see the output as a user would see it.

buildpacks/ruby/src/layers.rs

@@ -2,3 +2,4 @@ pub(crate) mod bundle_download_layer;
 pub(crate) mod bundle_install_layer;
 pub(crate) mod metrics_agent_install;
 pub(crate) mod ruby_install_layer;
+mod shared;

buildpacks/ruby/src/layers/ruby_install_layer.rs

@@ -11,22 +11,19 @@
 //!
 //! When the Ruby version changes, invalidate and re-run.
 //!
-use bullet_stream::state::SubBullet;
-use bullet_stream::{style, Print};
-use commons::display::SentenceList;
-use libcnb::data::layer_name;
-use libcnb::layer::{
- CachedLayerDefinition, EmptyLayerCause, InvalidMetadataAction, LayerState, RestoredLayerAction,
-};
-use libcnb::layer_env::LayerEnv;
-use magic_migrate::{try_migrate_deserializer_chain, TryMigrate};
-
+use crate::layers::shared::{cached_layer_write_metadata, MetadataDiff};
 use crate::{
  target_id::{TargetId, TargetIdError},
  RubyBuildpack, RubyBuildpackError,
 };
+use bullet_stream::state::SubBullet;
+use bullet_stream::{style, Print};
 use commons::gemfile_lock::ResolvedRubyVersion;
 use flate2::read::GzDecoder;
+use libcnb::data::layer_name;
+use libcnb::layer::{EmptyLayerCause, LayerState};
+use libcnb::layer_env::LayerEnv;
+use magic_migrate::{try_migrate_deserializer_chain, TryMigrate};
 use serde::{Deserialize, Deserializer, Serialize};
 use std::convert::Infallible;
 use std::io::{self, Stdout};
@@ -38,67 +35,26 @@ use url::Url;
 pub(crate) fn handle(
  context: &libcnb::build::BuildContext<RubyBuildpack>,
  mut bullet: Print<SubBullet<Stdout>>,
- metadata: Metadata,
+ metadata: &Metadata,
 ) -> libcnb::Result<(Print<SubBullet<Stdout>>, LayerEnv), RubyBuildpackError> {
- let layer_ref = context.cached_layer(
- layer_name!("ruby"),
- CachedLayerDefinition {
- build: true,
- launch: true,
- invalid_metadata_action: &|old| match Metadata::try_from_str_migrations(
- &toml::to_string(old).expect("TOML deserialization of GenericMetadata"),
- ) {
- Some(Ok(migrated)) => (
- InvalidMetadataAction::ReplaceMetadata(migrated),
- "replaced metadata".to_string(),
- ),
- Some(Err(error)) => (
- InvalidMetadataAction::DeleteLayer,
- format!("metadata migration error {error}"),
- ),
- None => (
- InvalidMetadataAction::DeleteLayer,
- "invalid metadata".to_string(),
- ),
- },
- restored_layer_action: &|old: &Metadata, _| {
- let diff = metadata_diff(old, &metadata);
- if diff.is_empty() {
- (
- RestoredLayerAction::KeepLayer,
- "using cached version".to_string(),
- )
- } else {
- (
- RestoredLayerAction::DeleteLayer,
- format!(
- "due to {changes}: {differences}",
- changes = if diff.len() > 1 { "changes" } else { "change" },
- differences = SentenceList::new(&diff)
- ),
- )
- }
- },
- },
- )?;
+ let layer_ref = cached_layer_write_metadata(layer_name!("ruby"), context, metadata)?;
  match &layer_ref.state {
- LayerState::Restored { cause: _ } => {
- bullet = bullet.sub_bullet("Using cached Ruby version");
+ LayerState::Restored { cause } => {
+ bullet = bullet.sub_bullet(cause);
  }
  LayerState::Empty { cause } => {
  match cause {
  EmptyLayerCause::NewlyCreated => {}
  EmptyLayerCause::InvalidMetadataAction { cause }
  | EmptyLayerCause::RestoredLayerAction { cause } => {
- bullet = bullet.sub_bullet(format!("Clearing cache {cause}"));
+ bullet = bullet.sub_bullet(cause);
  }
  }
  let timer = bullet.start_timer("Installing");
- install_ruby(&metadata, &layer_ref.path())?;
+ install_ruby(metadata, &layer_ref.path())?;
  bullet = timer.done();
  }
  }
- layer_ref.write_metadata(metadata)?;
  Ok((bullet, layer_ref.read_env()?))
 }
 
@@ -170,44 +126,39 @@ impl TryFrom<MetadataV1> for MetadataV2 {
  }
 }
 
-fn metadata_diff(old: &Metadata, metadata: &Metadata) -> Vec<String> {
- let mut differences = Vec::new();
- let Metadata {
- distro_name,
- distro_version,
- cpu_architecture,
- ruby_version,
- } = old;
- if ruby_version != &metadata.ruby_version {
- differences.push(format!(
- "Ruby version ({old} to {now})",
- old = style::value(ruby_version.to_string()),
- now = style::value(metadata.ruby_version.to_string())
- ));
- }
- if distro_name != &metadata.distro_name {
- differences.push(format!(
- "distro name ({old} to {now})",
- old = style::value(distro_name),
- now = style::value(&metadata.distro_name)
- ));
- }
- if distro_version != &metadata.distro_version {
- differences.push(format!(
- "distro version ({old} to {now})",
- old = style::value(distro_version),
- now = style::value(&metadata.distro_version)
- ));
- }
- if cpu_architecture != &metadata.cpu_architecture {
- differences.push(format!(
- "CPU architecture ({old} to {now})",
- old = style::value(cpu_architecture),
- now = style::value(&metadata.cpu_architecture)
- ));
- }
+impl MetadataDiff for Metadata {
+ fn diff(&self, old: &Self) -> Vec<String> {
+ let mut differences = Vec::new();
+ let Metadata {
+ distro_name,
+ distro_version,
+ cpu_architecture,
+ ruby_version,
+ } = old;
+ if ruby_version != &self.ruby_version {
+ differences.push(format!(
+ "Ruby version ({old} to {now})",
+ old = style::value(ruby_version.to_string()),
+ now = style::value(self.ruby_version.to_string())
+ ));
+ }
+ if distro_name != &self.distro_name || distro_version != &self.distro_version {
+ differences.push(format!(
+ "Distribution ({old} to {now})",
+ old = style::value(format!("{distro_name} {distro_version}")),
+ now = style::value(format!("{} {}", self.distro_name, self.distro_version))
+ ));
+ }
+ if cpu_architecture != &self.cpu_architecture {
+ differences.push(format!(
+ "CPU architecture ({old} to {now})",
+ old = style::value(cpu_architecture),
+ now = style::value(&self.cpu_architecture)
+ ));
+ }
 
- differences
+ differences
+ }
 }
 
 fn download_url(
@@ -291,6 +242,8 @@ pub(crate) enum RubyInstallError {
 
 #[cfg(test)]
 mod tests {
+ use crate::layers::shared::{strip_ansi, temp_build_context};
+
  use super::*;
 
  /// If this test fails due to a change you'll need to
@@ -362,4 +315,86 @@ version = "3.1.3"
  "https://heroku-buildpack-ruby.s3.us-east-1.amazonaws.com/heroku-22/ruby-2.7.4.tgz",
  );
  }
+
+ #[test]
+ fn metadata_diff_messages() {
+ let old = Metadata {
+ ruby_version: ResolvedRubyVersion("3.5.3".to_string()),
+ distro_name: "ubuntu".to_string(),
+ distro_version: "20.04".to_string(),
+ cpu_architecture: "amd64".to_string(),
+ };
+ assert_eq!(old.diff(&old), Vec::<String>::new());
+
+ let diff = Metadata {
+ ruby_version: ResolvedRubyVersion("3.5.5".to_string()),
+ distro_name: old.distro_name.clone(),
+ distro_version: old.distro_version.clone(),
+ cpu_architecture: old.cpu_architecture.clone(),
+ }
+ .diff(&old);
+ assert_eq!(
+ diff.iter().map(strip_ansi).collect::<Vec<String>>(),
+ vec!["Ruby version (`3.5.3` to `3.5.5`)".to_string()]
+ );
+
+ let diff = Metadata {
+ ruby_version: old.ruby_version.clone(),
+ distro_name: "alpine".to_string(),
+ distro_version: "3.20.0".to_string(),
+ cpu_architecture: old.cpu_architecture.clone(),
+ }
+ .diff(&old);
+
+ assert_eq!(
+ diff.iter().map(strip_ansi).collect::<Vec<String>>(),
+ vec!["Distribution (`ubuntu 20.04` to `alpine 3.20.0`)".to_string()]
+ );
+
+ let diff = Metadata {
+ ruby_version: old.ruby_version.clone(),
+ distro_name: old.distro_name.clone(),
+ distro_version: old.distro_version.clone(),
+ cpu_architecture: "arm64".to_string(),
+ }
+ .diff(&old);
+ assert_eq!(
+ diff.iter().map(strip_ansi).collect::<Vec<String>>(),
+ vec!["CPU architecture (`amd64` to `arm64`)".to_string()]
+ );
+ }
+
+ #[test]
+ fn test_ruby_version_difference_clears_cache() {
+ let temp = tempfile::tempdir().unwrap();
+ let context = temp_build_context::<RubyBuildpack>(temp.path());
+ let old = Metadata {
+ ruby_version: ResolvedRubyVersion("2.7.2".to_string()),
+ distro_name: "ubuntu".to_string(),
+ distro_version: "20.04".to_string(),
+ cpu_architecture: "x86_64".to_string(),
+ };
+ let differences = old.diff(&old);
+ assert_eq!(differences, Vec::<String>::new());
+
+ cached_layer_write_metadata(layer_name!("ruby"), &context, &old).unwrap();
+ let result = cached_layer_write_metadata(layer_name!("ruby"), &context, &old).unwrap();
+ let actual = result.state;
+ assert!(matches!(actual, LayerState::Restored { .. }));
+
+ let now = Metadata {
+ ruby_version: ResolvedRubyVersion("3.0.0".to_string()),
+ ..old.clone()
+ };
+ let differences = now.diff(&old);
+ assert_eq!(differences.len(), 1);
+
+ let result = cached_layer_write_metadata(layer_name!("ruby"), &context, &now).unwrap();
+ assert!(matches!(
+ result.state,
+ LayerState::Empty {
+ cause: EmptyLayerCause::RestoredLayerAction { .. }
+ }
+ ));
+ }
 }