mod lifecycle;
mod supervisor;
use async_trait::async_trait;
use serde::{Deserialize, Serialize};
use std::error::Error;
use std::fmt;
use std::time::Duration;
#[doc(hidden)]
pub mod __source {
pub const LIB: &str = include_str!("lib.rs");
pub const LIFECYCLE: &str = include_str!("lifecycle.rs");
pub const SUPERVISOR: &str = include_str!("supervisor.rs");
}
pub use lifecycle::{
ModuleDescriptor, ModuleEvent, ModuleObserver, ModulePhase, ModulePlan, ModuleRuntime,
ModuleStarter,
};
pub use supervisor::{
BackgroundTaskExit, BackgroundTaskExitKind, BackgroundTaskObserver, SupervisedTaskHandle,
};
pub const RUNTIME_API_VERSION: u32 = appstruct_contracts::RUNTIME_API.current;
pub const DEFAULT_SERVICE_SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(10);
#[must_use]
pub const fn supports_runtime_api(version: u32) -> bool {
appstruct_contracts::RUNTIME_API.supports(version)
}
pub type TenantId = uuid::Uuid;
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct Actor {
pub id: uuid::Uuid,
pub email: String,
pub roles: Vec<String>,
}
impl Actor {
#[must_use]
pub fn has_role(&self, role: &str) -> bool {
self.roles.iter().any(|candidate| candidate == role)
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct StartupError {
service: String,
message: String,
dependency_chain: Vec<String>,
rolled_back: Vec<String>,
rollback_failures: Vec<ShutdownFailure>,
}
impl StartupError {
#[must_use]
pub fn configuration(service: impl Into<String>, error: impl fmt::Display) -> Self {
Self {
service: service.into(),
message: error.to_string(),
dependency_chain: Vec::new(),
rolled_back: Vec::new(),
rollback_failures: Vec::new(),
}
}
#[must_use]
pub fn dependency(service: impl Into<String>, dependency: impl fmt::Display) -> Self {
Self::configuration(
service,
format_args!("runtime dependency `{dependency}` was not started"),
)
}
#[must_use]
pub fn service(&self) -> &str {
&self.service
}
#[must_use]
pub fn dependency_chain(&self) -> &[String] {
&self.dependency_chain
}
#[must_use]
pub fn rolled_back(&self) -> &[String] {
&self.rolled_back
}
#[must_use]
pub fn rollback_failures(&self) -> &[ShutdownFailure] {
&self.rollback_failures
}
#[must_use]
pub fn with_runtime_context(
mut self,
dependency_chain: Vec<String>,
rollback: ShutdownReport,
) -> Self {
self.dependency_chain = dependency_chain;
self.rolled_back = rollback.attempted;
self.rollback_failures = rollback.failures;
self
}
}
impl fmt::Display for StartupError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(
formatter,
"failed to initialize {}: {}",
self.service, self.message
)?;
if !self.dependency_chain.is_empty() {
write!(
formatter,
"; dependency chain: {}",
self.dependency_chain.join(" -> ")
)?;
}
if !self.rolled_back.is_empty() {
write!(formatter, "; rolled back: {}", self.rolled_back.join(", "))?;
}
if !self.rollback_failures.is_empty() {
write!(
formatter,
"; rollback failures: {}",
self.rollback_failures
.iter()
.map(ToString::to_string)
.collect::<Vec<_>>()
.join(", ")
)?;
}
Ok(())
}
}
impl Error for StartupError {}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ShutdownError {
message: String,
}
impl ShutdownError {
#[must_use]
pub fn new(error: impl fmt::Display) -> Self {
Self {
message: error.to_string(),
}
}
}
impl fmt::Display for ShutdownError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(&self.message)
}
}
impl Error for ShutdownError {}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ShutdownFailureKind {
Error,
Timeout,
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ShutdownFailure {
pub service: String,
pub kind: ShutdownFailureKind,
pub message: String,
}
impl fmt::Display for ShutdownFailure {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(formatter, "{}: {}", self.service, self.message)
}
}
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct ShutdownReport {
pub attempted: Vec<String>,
pub failures: Vec<ShutdownFailure>,
}
impl ShutdownReport {
#[must_use]
pub fn is_success(&self) -> bool {
self.failures.is_empty()
}
}
impl fmt::Display for ShutdownReport {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
if self.failures.is_empty() {
formatter.write_str("shutdown completed")
} else {
write!(
formatter,
"shutdown failed: {}",
self.failures
.iter()
.map(ToString::to_string)
.collect::<Vec<_>>()
.join(", ")
)
}
}
}
#[async_trait]
pub trait ServiceHandle: Send {
fn service(&self) -> &'static str;
async fn shutdown(self: Box<Self>) -> Result<(), ShutdownError>;
}
#[derive(Default)]
pub struct ServiceHandles {
handles: Vec<Box<dyn ServiceHandle>>,
}
impl ServiceHandles {
#[must_use]
pub fn new() -> Self {
Self::default()
}
pub fn push(&mut self, handle: impl ServiceHandle + 'static) {
self.handles.push(Box::new(handle));
}
pub fn push_boxed(&mut self, handle: Box<dyn ServiceHandle>) {
self.handles.push(handle);
}
#[must_use]
pub fn len(&self) -> usize {
self.handles.len()
}
#[must_use]
pub fn is_empty(&self) -> bool {
self.handles.is_empty()
}
pub async fn shutdown_reverse(&mut self) -> ShutdownReport {
self.shutdown_reverse_with_timeout(DEFAULT_SERVICE_SHUTDOWN_TIMEOUT)
.await
}
pub async fn shutdown_reverse_with_timeout(&mut self, timeout: Duration) -> ShutdownReport {
let mut report = ShutdownReport {
attempted: Vec::with_capacity(self.handles.len()),
failures: Vec::new(),
};
while let Some(handle) = self.handles.pop() {
let service = handle.service().to_owned();
report.attempted.push(service.clone());
match tokio::time::timeout(timeout, handle.shutdown()).await {
Ok(Ok(())) => {}
Ok(Err(error)) => report.failures.push(ShutdownFailure {
service,
kind: ShutdownFailureKind::Error,
message: error.to_string(),
}),
Err(_) => report.failures.push(ShutdownFailure {
service,
kind: ShutdownFailureKind::Timeout,
message: format!("did not stop within {} ms", timeout.as_millis()),
}),
}
}
report
}
}
#[cfg(test)]
mod tests {
use super::{
RUNTIME_API_VERSION, ServiceHandle, ServiceHandles, ShutdownError, ShutdownFailureKind,
supports_runtime_api,
};
use async_trait::async_trait;
use std::sync::{Arc, Mutex};
struct RecordingHandle {
service: &'static str,
stopped: Arc<Mutex<Vec<&'static str>>>,
}
#[async_trait]
impl ServiceHandle for RecordingHandle {
fn service(&self) -> &'static str {
self.service
}
async fn shutdown(self: Box<Self>) -> Result<(), ShutdownError> {
self.stopped.lock().unwrap().push(self.service);
Ok(())
}
}
#[tokio::test]
async fn stops_services_in_reverse_startup_order() {
let stopped = Arc::new(Mutex::new(Vec::new()));
let mut handles = ServiceHandles::new();
for service in ["auth", "jobs", "web"] {
handles.push(RecordingHandle {
service,
stopped: Arc::clone(&stopped),
});
}
let report = handles.shutdown_reverse().await;
assert_eq!(report.attempted, ["web", "jobs", "auth"]);
assert!(report.is_success());
assert_eq!(*stopped.lock().unwrap(), ["web", "jobs", "auth"]);
assert!(handles.is_empty());
}
struct FailingHandle {
service: &'static str,
hangs: bool,
}
#[async_trait]
impl ServiceHandle for FailingHandle {
fn service(&self) -> &'static str {
self.service
}
async fn shutdown(self: Box<Self>) -> Result<(), ShutdownError> {
if self.hangs {
std::future::pending().await
} else {
Err(ShutdownError::new("injected shutdown error"))
}
}
}
#[tokio::test]
async fn reports_shutdown_errors_and_timeouts_without_skipping_services() {
let mut handles = ServiceHandles::new();
handles.push(FailingHandle {
service: "failure",
hangs: false,
});
handles.push(FailingHandle {
service: "timeout",
hangs: true,
});
let report = handles
.shutdown_reverse_with_timeout(std::time::Duration::from_millis(1))
.await;
assert_eq!(report.attempted, ["timeout", "failure"]);
assert_eq!(report.failures.len(), 2);
assert_eq!(report.failures[0].kind, ShutdownFailureKind::Timeout);
assert_eq!(report.failures[1].kind, ShutdownFailureKind::Error);
}
#[test]
fn runtime_api_compatibility_is_explicit() {
assert!(supports_runtime_api(RUNTIME_API_VERSION));
assert!(!supports_runtime_api(RUNTIME_API_VERSION + 1));
}
}