libcnb 0.30.4

A framework for writing Cloud Native Buildpacks in Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

//! Provides detect phase specific types and helpers.

use crate::Target;
use crate::buildpack::Buildpack;
use crate::{data::build_plan::BuildPlan, data::buildpack::ComponentBuildpackDescriptor};
use std::fmt::Debug;
use std::path::PathBuf;

/// Context for the detect phase execution.
pub struct DetectContext<B: Buildpack + ?Sized> {
    pub app_dir: PathBuf,
    pub buildpack_dir: PathBuf,
    pub target: Target,
    pub platform: B::Platform,
    pub buildpack_descriptor: ComponentBuildpackDescriptor<B::Metadata>,
}

/// Describes the result of the detect phase.
///
/// Besides indicating passing or failing detection, it also contains detect phase output such as
/// the build plan. To construct values of this type, use a [`DetectResultBuilder`].
#[derive(Debug)]
#[must_use]
pub struct DetectResult(pub(crate) InnerDetectResult);

#[derive(Debug)]
pub(crate) enum InnerDetectResult {
    Fail,
    Pass { build_plan: Option<BuildPlan> },
}

/// Constructs [`DetectResult`] values.
///
/// # Examples:
/// ```
/// use libcnb::detect::{DetectResult, DetectResultBuilder};
/// use libcnb_data::build_plan::BuildPlanBuilder;
///
/// let simple_pass: Result<DetectResult, ()> = DetectResultBuilder::pass().build();
/// let simple_fail: Result<DetectResult, ()> = DetectResultBuilder::fail().build();
///
/// let with_build_plan: Result<DetectResult, ()> = DetectResultBuilder::pass()
///     .build_plan(BuildPlanBuilder::new().provides("something").build())
///     .build();
/// ```
#[must_use]
pub struct DetectResultBuilder;

impl DetectResultBuilder {
    pub fn pass() -> PassDetectResultBuilder {
        PassDetectResultBuilder { build_plan: None }
    }

    pub fn fail() -> FailDetectResultBuilder {
        FailDetectResultBuilder {}
    }
}

/// Constructs [`DetectResult`] values for a passed detection. Can't be used directly, use
/// a [`DetectResultBuilder`] to create an instance.
#[must_use]
pub struct PassDetectResultBuilder {
    build_plan: Option<BuildPlan>,
}

impl PassDetectResultBuilder {
    /// Builds the final [`DetectResult`].
    ///
    /// This method returns the [`DetectResult`] wrapped in a [`Result`] even though its technically
    /// not fallible. This is done to simplify using this method in the context it's most often used
    /// in: a buildpack's [detect method](crate::Buildpack::detect).
    ///
    /// See [`build_unwrapped`](Self::build_unwrapped) for an unwrapped version of this method.
    pub fn build<E>(self) -> Result<DetectResult, E> {
        Ok(self.build_unwrapped())
    }

    pub fn build_unwrapped(self) -> DetectResult {
        DetectResult(InnerDetectResult::Pass {
            build_plan: self.build_plan,
        })
    }

    pub fn build_plan(mut self, build_plan: BuildPlan) -> Self {
        self.build_plan = Some(build_plan);
        self
    }
}

/// Constructs [`DetectResult`] values for a failed detection. Can't be used directly, use
/// a [`DetectResultBuilder`] to create an instance.
#[must_use]
pub struct FailDetectResultBuilder;

impl FailDetectResultBuilder {
    /// Builds the final [`DetectResult`].
    ///
    /// This method returns the [`DetectResult`] wrapped in a [`Result`] even though its technically
    /// not fallible. This is done to simplify using this method in the context it's most often used
    /// in: a buildpack's [detect method](crate::Buildpack::detect).
    ///
    /// See [`build_unwrapped`](Self::build_unwrapped) for an unwrapped version of this method.
    pub fn build<E>(self) -> Result<DetectResult, E> {
        Ok(self.build_unwrapped())
    }

    #[allow(clippy::unused_self)]
    pub fn build_unwrapped(self) -> DetectResult {
        DetectResult(InnerDetectResult::Fail)
    }
}