Skip to main content

tuwunel_service/storage/
mod.rs

1//! Configured object-storage providers for media and other binary data.
2//!
3//! The service builds local-filesystem and S3-compatible backends behind one
4//! provider API. A local media provider rooted under the database directory is
5//! supplied when no explicit `media` provider is configured.
6
7/// Backend implementations and the common provider interface.
8///
9/// Provider instances normalize paths, transfers, and optional URL signing
10/// across local and S3-compatible object stores.
11/// The module also owns backend construction and startup connectivity checks.
12pub mod provider;
13
14use std::{collections::BTreeMap, sync::Arc};
15
16use async_trait::async_trait;
17use derive_more::Debug;
18use futures::TryStreamExt;
19/// Object-store transfer types used by provider APIs.
20///
21/// Re-exporting these types keeps callers independent of the service's direct
22/// object-store dependency path. Their behavior is supplied by the selected
23/// storage backend.
24pub use object_store::{CopyMode, GetResult, GetResultPayload, PutPayload, PutResult};
25#[cfg(not(all(feature = "gcs_storage", feature = "s3_storage")))]
26use tuwunel_core::Err;
27use tuwunel_core::{
28	Result, at, config::StorageProvider, err, implement, utils::stream::IterStream,
29};
30
31/// A configured object-storage provider.
32///
33/// Each provider wraps one local or S3-compatible backend and applies its
34/// configured path and transfer policies.
35/// Callers share the provider through the service registry's [`Arc`] values.
36pub use self::provider::Provider;
37
38/// Registry of configured object-storage providers.
39///
40/// The registry includes every enabled provider and supplies a default local
41/// `media` provider when the configuration does not define one.
42/// Provider identifiers determine lookup and iteration order.
43#[derive(Debug)]
44pub struct Service {
45	providers: Providers,
46
47	#[debug(skip)]
48	services: Arc<crate::services::OnceServices>,
49}
50
51type Providers = BTreeMap<String, Arc<Provider>>;
52
53#[async_trait]
54impl crate::Service for Service {
55	fn build(args: &crate::Args<'_>) -> Result<Arc<Self>> {
56		Ok(Arc::new(Self {
57			services: args.services.clone(),
58			providers: Self::build_providers(args)?,
59		}))
60	}
61
62	async fn worker(self: Arc<Self>) -> Result {
63		self.start_providers().await?;
64
65		Ok(())
66	}
67
68	fn name(&self) -> &str { crate::service::make_name(std::module_path!()) }
69}
70
71#[implement(Service)]
72#[tracing::instrument(
73	level = "info",
74	err(level = "error")
75	skip_all,
76)]
77fn build_providers(args: &crate::Args<'_>) -> Result<Providers> {
78	args.server
79		.config
80		.storage_provider_sections()
81		.filter_map(|(name, conf)| match conf.as_ref() {
82			| StorageProvider::local(conf) => provider::local::new(args, name, conf).transpose(),
83			#[cfg(feature = "s3_storage")]
84			| StorageProvider::s3(conf) => provider::s3::new(args, name, conf).transpose(),
85			#[cfg(feature = "gcs_storage")]
86			| StorageProvider::gcs(conf) => provider::gcs::new(args, name, conf).transpose(),
87			#[cfg(not(feature = "s3_storage"))]
88			| StorageProvider::s3(conf) if conf.is_enabled() => Some(Err!(Config(
89				"storage_provider",
90				"tuwunel was not built with S3 support (\"s3_storage\") for provider {name:?}"
91			))),
92			#[cfg(not(feature = "gcs_storage"))]
93			| StorageProvider::gcs(conf) if conf.is_enabled() => Some(Err!(Config(
94				"storage_provider",
95				"tuwunel was not built with GCS support (\"gcs_storage\") for provider {name:?}"
96			))),
97			| _ => None,
98		})
99		.collect::<Result<_>>()
100}
101
102#[implement(Service)]
103async fn start_providers(&self) -> Result {
104	self.providers
105		.iter()
106		.map(at!(1))
107		.try_stream()
108		.and_then(Provider::start)
109		.try_collect()
110		.await
111}
112
113/// Returns the storage provider with the exact identifier `id`.
114///
115/// A missing or disabled provider produces a not-found request error. The
116/// returned provider remains owned by this service.
117#[implement(Service)]
118pub fn provider<'a>(&'a self, id: &'a str) -> Result<&'a Arc<Provider>> {
119	self.providers
120		.get(id)
121		.ok_or_else(|| err!(Request(NotFound(error!("No instance of provider")))))
122}
123
124/// Returns the first provider configuration whose identifier starts with `id`.
125///
126/// This uses the same prefix filter as [`Self::configs`], so callers requiring
127/// an exact match should validate the returned identifier separately.
128#[implement(Service)]
129pub fn config<'a>(&'a self, id: &'a str) -> Result<&'a StorageProvider> {
130	self.configs(Some(id))
131		.next()
132		.map(at!(1))
133		.ok_or_else(|| err!(Request(NotFound("No configuration for provider"))))
134}
135
136/// Iterates over the enabled storage-provider instances.
137///
138/// Iteration follows the registry's identifier order. Each item remains owned
139/// by this service and can be shared by cloning its [`Arc`].
140#[implement(Service)]
141pub fn providers(&self) -> impl Iterator<Item = &Arc<Provider>> + Send + '_ {
142	self.providers.values()
143}
144
145/// Iterates over configured providers, optionally filtered by identifier prefix.
146///
147/// Passing `None` yields every configuration, while `Some(id)` yields entries
148/// whose identifiers start with `id`. Disabled configurations can appear here
149/// even though they have no corresponding [`Provider`] instance.
150#[implement(Service)]
151pub fn configs<'a, Id>(
152	&'a self,
153	id: Id,
154) -> impl Iterator<Item = (&'a String, &'a StorageProvider)> + Send + 'a
155where
156	Id: Into<Option<&'a str>>,
157{
158	let id = id.into();
159
160	self.services
161		.config
162		.storage_provider
163		.iter()
164		.filter(move |(id_, _)| id.is_none_or(|id| id_.starts_with(id)))
165}