rocket/
phase.rs

Help
1use state::TypeMap;
2use figment::Figment;
3
4use crate::listener::Endpoint;
5use crate::shutdown::Stages;
6use crate::{Catcher, Config, Rocket, Route};
7use crate::router::{Router, Finalized};
8use crate::fairing::Fairings;
9
10mod private {
11    pub trait Sealed {  }
12}
13
14#[doc(hidden)]
15pub trait Stateful: private::Sealed {
16    fn into_state(self) -> State;
17    fn as_ref(&self) -> StateRef<'_>;
18    fn as_mut(&mut self) -> StateRefMut<'_>;
19}
20
21/// A marker trait for Rocket's launch phases.
22///
23/// This treat is implemented by the three phase marker types: [`Build`],
24/// [`Ignite`], and [`Orbit`], representing the three phases to launch an
25/// instance of [`Rocket`]. This trait is _sealed_ and cannot be implemented
26/// outside of Rocket.
27///
28/// For a description of the three phases, see [`Rocket#phases`].
29pub trait Phase: private::Sealed {
30    #[doc(hidden)]
31    type State: std::fmt::Debug + Stateful + Sync + Send + Unpin;
32}
33
34macro_rules! phase {
35    ($(#[$o:meta])* $P:ident ($(#[$i:meta])* $S:ident) { $($fields:tt)* }) => (
36        $(#[$o])*
37        pub enum $P { }
38
39        impl Phase for $P {
40            #[doc(hidden)]
41            type State = $S;
42        }
43
44        $(#[$i])*
45        #[doc(hidden)]
46        pub struct $S {
47            $($fields)*
48        }
49
50        impl Stateful for $S {
51            fn into_state(self) -> State { State::$P(self) }
52            fn as_ref(&self) -> StateRef<'_> { StateRef::$P(self) }
53            fn as_mut(&mut self) -> StateRefMut<'_> { StateRefMut::$P(self) }
54        }
55
56        #[doc(hidden)]
57        impl From<$S> for Rocket<$P> {
58            fn from(s: $S) -> Self { Rocket(s) }
59        }
60
61        impl private::Sealed for $P {}
62
63        impl private::Sealed for $S {}
64    )
65}
66
67macro_rules! phases {
68    ($($(#[$o:meta])* $P:ident ($(#[$i:meta])* $S:ident) { $($fields:tt)* })*) => (
69        #[doc(hidden)]
70        pub enum State { $($P($S)),* }
71
72        #[doc(hidden)]
73        pub enum StateRef<'a> { $($P(&'a $S)),* }
74
75        #[doc(hidden)]
76        pub enum StateRefMut<'a> { $($P(&'a mut $S)),* }
77
78        $(phase!($(#[$o])* $P ($(#[$i])* $S) { $($fields)* });)*
79    )
80}
81
82phases! {
83    /// The initial launch [`Phase`]. See [Rocket#build](`Rocket#build`) for
84    /// phase details.
85    ///
86    /// An instance of `Rocket` in this phase is typed as [`Rocket<Build>`]: a
87    /// transient, in-progress build.
88    Build (#[derive(Default, Debug)] Building) {
89        pub(crate) routes: Vec<Route>,
90        pub(crate) catchers: Vec<Catcher>,
91        pub(crate) fairings: Fairings,
92        pub(crate) figment: Figment,
93        pub(crate) state: TypeMap![Send + Sync],
94    }
95
96    /// The second launch [`Phase`]: post-build but pre-orbit. See
97    /// [Rocket#ignite](`Rocket#ignite`) for details.
98    ///
99    /// An instance of `Rocket` in this phase is typed as [`Rocket<Ignite>`] and
100    /// represents a fully built and finalized application server ready for
101    /// launch into orbit. See [`Rocket#ignite`] for full details.
102    Ignite (#[derive(Debug)] Igniting) {
103        pub(crate) router: Router<Finalized>,
104        pub(crate) fairings: Fairings,
105        pub(crate) figment: Figment,
106        pub(crate) config: Config,
107        pub(crate) state: TypeMap![Send + Sync],
108        pub(crate) shutdown: Stages,
109    }
110
111    /// The final launch [`Phase`]. See [Rocket#orbit](`Rocket#orbit`) for
112    /// details.
113    ///
114    /// An instance of `Rocket` in this phase is typed as [`Rocket<Orbit>`] and
115    /// represents a running application.
116    Orbit (#[derive(Debug)] Orbiting) {
117        pub(crate) router: Router<Finalized>,
118        pub(crate) fairings: Fairings,
119        pub(crate) figment: Figment,
120        pub(crate) config: Config,
121        pub(crate) state: TypeMap![Send + Sync],
122        pub(crate) shutdown: Stages,
123        pub(crate) endpoints: Vec<Endpoint>,
124    }
125}
rocket/phase.rs

rocket/
phase.rs
