Skip to main content

tuwunel_core/config/
media.rs

1//! Configures media storage and processing.
2//!
3//! Upload and storage settings control how originals enter the repository.
4//! Thumbnail, URL preview, and import settings govern derived and migrated media.
5
6use std::{collections::BTreeSet, net::IpAddr, path::PathBuf};
7
8use either::Either;
9use regex::RegexSet;
10use serde::Deserialize;
11use tuwunel_macros::config_example_generator;
12
13use super::{deserialize_bytesize_u64, deserialize_bytesize_usize, true_fn};
14use crate::{implement, utils::set::is_empty_or_contains};
15
16/// Media repository
17///
18/// Uploads, storage, downloads and the legacy media endpoints, with
19/// sub-sections for Conduit media import, thumbnails, URL previews and
20/// video thumbnails. Every key has a working default; with nothing set,
21/// media is kept in `<database_path>/media` by the built-in local provider
22/// `media`, which a `[global.storage_provider.media.local]` (or `.s3`,
23/// `.gcs`) section replaces.
24///
25/// Reads try the providers in `storage_providers`, in name order, until
26/// one holds the file; uploads go to those in `store_on_providers`, or to
27/// all of them when it is empty. Any name other than `media` needs its own
28/// `[global.storage_provider.<ID>.*]` section.
29///
30/// Example (new uploads to S3, older files still read from disk):
31///
32/// ```toml
33///     [global.media]
34///     storage_providers = ["media", "media_on_s3"]
35///     store_on_providers = ["media_on_s3"]
36///
37///     [global.storage_provider.media_on_s3.s3]
38///     bucket = "matrix-media"
39///     key = "ACCESS_KEY_ID"
40///     secret = "SECRET_ACCESS_KEY"
41/// ```
42///
43/// Tips:
44/// - The config is refused when `store_on_providers` names a provider
45///   missing from `storage_providers`, or `storage_providers` names one
46///   (other than `media`) with no `[global.storage_provider.<ID>.*]`
47///   section. An S3 or GCS section without `bucket` (or S3 `url`), or a
48///   local one with `base_path = ""`, passes that check but is skipped at
49///   startup; skipping is an error only when it leaves no enabled provider
50///   to receive uploads.
51/// - Several `storage_providers` with `store_on_providers` empty copies
52///   every upload to all of them; a startup warning says so.
53/// - Copy existing files to a new provider with
54///   `!admin query storage sync media media_on_s3`, then drop `media` from
55///   both lists.
56/// - Provider sections are read only at startup, so a config reload that
57///   adds, removes or changes one is refused; restart instead.
58#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
59#[derive(Clone, Debug, Deserialize)]
60#[config_example_generator(
61	filename = "tuwunel-example.toml",
62	section = "global.media",
63	group = "true",
64	ignore = "import thumbnail url_preview video_thumbnail"
65)]
66pub struct Media {
67	/// Limits the number of concurrent pending asynchronous media uploads per
68	/// user.
69	///
70	/// reloadable: yes
71	/// default: 5
72	/// legacy: max_pending_media_uploads
73	#[serde(default = "default_max_pending_uploads")]
74	pub max_pending_uploads: usize,
75
76	/// Sets the lifetime in seconds before an unused pending MXC URI expires
77	/// and is removed.
78	///
79	/// reloadable: yes
80	/// default: 86400 (24 hours)
81	/// legacy: media_create_unused_expiration_time
82	#[serde(default = "default_create_unused_expiration_time")]
83	pub create_unused_expiration_time: u64,
84
85	/// Limits media create requests per second from one user.
86	///
87	/// reloadable: yes
88	/// default: 10
89	/// legacy: media_rc_create_per_second
90	#[serde(default = "default_rc_create_per_second")]
91	pub rc_create_per_second: u32,
92
93	/// Limits the burst count of media create requests from one user.
94	///
95	/// reloadable: yes
96	/// default: 50
97	/// legacy: media_rc_create_burst_count
98	#[serde(default = "default_rc_create_burst_count")]
99	pub rc_create_burst_count: u32,
100
101	/// Sets the writable space threshold below which local media uploads are
102	/// refused.
103	///
104	/// Each local storage provider receiving the upload is checked, excluding
105	/// blocks reserved for privileged processes. Media is stored beside the
106	/// database by default, and a full disk prevents database writes, so
107	/// uploads stop first with M_RESOURCE_LIMIT_EXCEEDED and resume when space
108	/// returns. Remote media, URL previews, and thumbnails are never refused.
109	/// Accepts an integer byte count or an SI/IEC string such as "10 GiB"; 0
110	/// disables the check for cases such as a network mount reporting no free
111	/// space.
112	///
113	/// reloadable: yes
114	/// default: "1 GiB"
115	/// legacy: media_upload_min_free_space
116	#[serde(
117		default = "default_upload_min_free_space",
118		deserialize_with = "deserialize_bytesize_u64"
119	)]
120	pub upload_min_free_space: u64,
121
122	/// Prevents media from being embedded in frames, including same-origin
123	/// frames.
124	///
125	/// The default is disabled for compatibility with attachment viewers.
126	/// Enabling it adds `frame-ancestors 'none'` to download and thumbnail
127	/// Content-Security-Policy headers. Changes require a restart, and reverse
128	/// proxy headers may still prevent framing.
129	///
130	/// legacy: media_deny_framing
131	#[serde(default)]
132	pub deny_framing: bool,
133
134	/// Prevents inline styles in media documents.
135	///
136	/// The default is disabled so browser image viewers retain their
137	/// presentation styles. Enabling it omits `style-src 'unsafe-inline'` from
138	/// download and thumbnail Content-Security-Policy headers. Changes require
139	/// a restart, and reverse proxy headers may still restrict styles.
140	///
141	/// legacy: media_deny_inline_styles
142	#[serde(default)]
143	pub deny_inline_styles: bool,
144
145	/// Enables the legacy unauthenticated Matrix media repository endpoints.
146	///
147	/// These are `/_matrix/media/*/config`, `/_matrix/media/*/preview_url`,
148	/// `/_matrix/media/*/download/*`, and `/_matrix/media/*/thumbnail/*`. The
149	/// authenticated equivalents are always enabled. The default is false.
150	///
151	/// legacy: allow_legacy_media
152	#[serde(default)]
153	pub allow_legacy: bool,
154
155	/// Falls back to requesting legacy unauthenticated media from remote
156	/// servers.
157	///
158	/// Unauthenticated media was removed around the third quarter of 2024.
159	/// Enabling this adds considerable federation requests that are unlikely
160	/// to succeed.
161	///
162	/// reloadable: yes
163	/// legacy: request_legacy_media
164	#[serde(default)]
165	pub request_legacy: bool,
166
167	/// Permits fetching remote legacy content and thumbnails when true.
168	///
169	/// When false, those remote legacy requests are rejected.
170	///
171	/// reloadable: yes
172	/// legacy: freeze_legacy_media
173	#[serde(default = "true_fn")]
174	pub freeze_legacy: bool,
175
176	/// Checks media directory consistency at startup.
177	///
178	/// Together with `media.compat_file_link`, this upgrades media when
179	/// switching between Conduit and tuwunel; both options must be enabled.
180	/// Startup checks can also remove database entries for files deleted from
181	/// the media directory. If neither check applies and the directory is
182	/// large, disabling this may reduce startup time.
183	///
184	/// legacy: media_startup_check
185	#[serde(default = "true_fn")]
186	pub startup_check: bool,
187
188	/// Creates media symlinks for compatibility with Conduit's media
189	/// directory.
190	///
191	/// This is needed only when planning to use Conduit again; disabling it
192	/// reduces filesystem clutter and symlink management overhead. It is
193	/// disabled by default. Before returning to upstream Conduit, run tuwunel
194	/// at least once with this enabled and allow `media.startup_check` to
195	/// finish before shutdown.
196	///
197	/// legacy: media_compat_file_link
198	#[serde(default)]
199	pub compat_file_link: bool,
200
201	/// Removes missing media metadata during startup checks.
202	///
203	/// Deleting files from the media directory then removes their
204	/// corresponding database entries. This is disabled by default because
205	/// accidentally moving the directory or making it inaccessible would
206	/// otherwise lose database metadata.
207	///
208	/// legacy: prune_missing_media
209	#[serde(default)]
210	pub prune_missing: bool,
211
212	/// Selects storage providers used for media.
213	///
214	/// Configure each listed name at `global.storage_provider.<NAME>.<brand>`;
215	/// multiple entries support advanced features and future extensions, but
216	/// require checking related settings to avoid resource duplication costs
217	/// and poor performance. The default `["media"]` is an implicit provider
218	/// for the local media directory. Configure
219	/// `global.storage_provider.media.local` to alter it, or omit "media" from
220	/// this list to disable it. Existing deployments should retain "media" as
221	/// a fallback alongside a new provider.
222	///
223	/// reloadable: yes
224	/// default: ["media"]
225	/// legacy: media_storage_providers
226	#[allow(
227		clippy::doc_link_with_quotes,
228		clippy::allow_attributes,
229		reason = "configuration arrays contain literal quoted strings, not intra-doc links"
230	)]
231	#[serde(default = "default_storage_providers")]
232	pub storage_providers: BTreeSet<String>,
233
234	/// Selects configured storage providers that receive new media.
235	///
236	/// When not explicitly configured, all entries in
237	/// `media.storage_providers` are used. Each selected provider must also
238	/// appear there. This supports passive migration by writing to a new
239	/// provider while querying the old one as a fallback, for example
240	/// `media.storage_providers = ["media", "media_on_s3"]` with
241	/// `media.store_on_providers = ["media_on_s3"]`.
242	///
243	/// reloadable: yes
244	/// default: []
245	/// legacy: store_media_on_providers
246	#[serde(default)]
247	pub store_on_providers: BTreeSet<String>,
248
249	/// Redirects local media downloads when the client requests
250	/// `allow_redirect=true` under MSC3860.
251	///
252	/// If a configured provider can presign the object, such as S3, the server
253	/// returns a 307 redirect to a short-lived URL instead of proxying the
254	/// bytes. Media stored only on the local filesystem is always served
255	/// directly.
256	///
257	/// reloadable: yes
258	/// default: false
259	/// legacy: media_allow_redirect
260	#[serde(default)]
261	pub allow_redirect: bool,
262
263	/// Lists server-name regex patterns from which remote media downloads are
264	/// refused.
265	///
266	/// reloadable: yes
267	/// example: ['badserver\.tld$', 'badphrase', '19dollarfortnitecards']
268	///
269	/// default: []
270	/// legacy: prevent_media_downloads_from
271	#[serde(default, with = "serde_regex")]
272	pub prevent_downloads_from: RegexSet,
273
274	/// Settings for media import.
275	///
276	/// display: section
277	#[serde(default)]
278	pub import: Import,
279
280	/// Settings for media thumbnail.
281	///
282	/// display: section
283	#[serde(default)]
284	pub thumbnail: Thumbnail,
285
286	/// Settings for media url preview.
287	///
288	/// display: section
289	#[serde(default)]
290	pub url_preview: UrlPreview,
291
292	/// Settings for media video thumbnail.
293	///
294	/// display: section
295	#[serde(default)]
296	pub video_thumbnail: VideoThumbnail,
297}
298
299/// Media import
300///
301/// Settings for importing media from a database created by another
302/// server. Conduit is the only supported source, configured in
303/// `[global.media.import.conduit]`; nothing here needs setting for a
304/// database that did not come from Conduit.
305#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
306#[derive(Clone, Debug, Default, Deserialize)]
307#[config_example_generator(
308	filename = "tuwunel-example.toml",
309	section = "global.media.import",
310	group = "true",
311	ignore = "conduit"
312)]
313pub struct Import {
314	/// Settings for media import conduit.
315	///
316	/// display: section
317	#[serde(default)]
318	pub conduit: ImportConduit,
319}
320
321/// Conduit media import
322///
323/// When the server first starts on a database taken over from Conduit, it
324/// copies each original media file into its own store through the normal
325/// upload path, so the copies land on the providers that receive uploads
326/// (see `[global.media]`). With nothing set, the files are read from
327/// `<database_path>/media` in Conduit's default directory layout.
328///
329/// Set `source_path` when Conduit kept media in another directory, or
330/// `source_provider` when it kept media in object storage.
331///
332/// Example (importing from an S3 bucket):
333///
334/// ```toml
335///     [global.media.import.conduit]
336///     source_provider = "conduit_source"
337///
338///     [global.storage_provider.conduit_source.s3]
339///     bucket = "conduit-media"
340///     key = "ACCESS_KEY_ID"
341///     secret = "SECRET_ACCESS_KEY"
342/// ```
343///
344/// Tips:
345/// - The import runs once and is then recorded as done; changing these
346///   keys afterwards has no effect.
347/// - The source provider needs no entry in `media.storage_providers`.
348///   Keep it out of that list, and keep the list non-empty, so imported
349///   files are not also written back into the source.
350/// - A `source_provider` that names no defined provider, or stays
351///   unreachable after a retry, fails startup; the next start repeats the
352///   import from the beginning. Missing source files are skipped.
353/// - When `directory_depth` is non-zero, `directory_length` must be
354///   non-zero and their product under 64, or the config is refused.
355#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
356#[derive(Clone, Debug, Deserialize)]
357#[config_example_generator(
358	filename = "tuwunel-example.toml",
359	section = "global.media.import.conduit",
360	group = "true"
361)]
362pub struct ImportConduit {
363	/// Selects Conduit's media directory when importing its database in place.
364	///
365	/// Leave unset to use `<database_path>/media`, which is Conduit's default
366	/// location.
367	///
368	/// example: "/var/lib/matrix-conduit/media"
369	/// legacy: conduit_source_media_path
370	pub source_path: Option<PathBuf>,
371
372	/// Sets the source media directory sharding depth for a Conduit import.
373	///
374	/// Use 0 for a flat directory. This must match the source Conduit's
375	/// `media.directory_structure`; the default matches its `Deep { length =
376	/// 2, depth = 2 }`.
377	///
378	/// default: 2
379	/// legacy: conduit_media_directory_depth
380	#[serde(default = "default_directory_depth")]
381	pub directory_depth: u8,
382
383	/// Sets the source shard-segment length for a Conduit media import.
384	///
385	/// Use it with `media.import.conduit.directory_depth` to describe the
386	/// source directory layout.
387	///
388	/// default: 2
389	/// legacy: conduit_media_directory_length
390	#[serde(default = "default_directory_length")]
391	pub directory_length: u8,
392
393	/// Selects the storage provider containing source originals for a Conduit
394	/// S3 import.
395	///
396	/// Name a `[global.storage_provider.<name>]` entry, or leave unset to read
397	/// the filesystem at `media.import.conduit.source_path`. Configure that
398	/// provider with Conduit's S3 credentials and set `base_path` to Conduit's
399	/// `media.path` prefix. Content-addressed object keys use
400	/// `media.import.conduit.directory_depth` and
401	/// `media.import.conduit.directory_length` for sharding. Restrict
402	/// `media.storage_providers` to destination providers, such as
403	/// `["media"]`, or the importer also copies media back into the read-only
404	/// source bucket.
405	///
406	/// example: "conduit_source"
407	/// legacy: conduit_source_media_provider
408	pub source_provider: Option<String>,
409}
410
411/// Image thumbnails
412///
413/// Limits on the thumbnails generated on demand from images, and from the
414/// frames extracted for video thumbnails. Image thumbnails need no setup;
415/// these keys bound the work each one may cost and how many sources are
416/// processed at once.
417///
418/// Tips:
419/// - The config is refused when `max_pixels` is 0 or
420///   `animated_concurrency` is outside 1 to 1024.
421/// - Video thumbnails also need `[global.media.video_thumbnail]`, which is
422///   off until its `command` is set.
423#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
424#[derive(Clone, Copy, Debug, Deserialize)]
425#[config_example_generator(
426	filename = "tuwunel-example.toml",
427	section = "global.media.thumbnail",
428	group = "true"
429)]
430pub struct Thumbnail {
431	/// Limits the pixel count the thumbnailer will decode.
432	///
433	/// Images declaring more pixels receive no thumbnail because dimensions
434	/// consume memory regardless of encoded file size; video frames inherit
435	/// the video resolution and share this bound. The default 50 megapixels is
436	/// roughly four 8K frames and exceeds ordinary camera output. Four bytes
437	/// are budgeted per pixel, admitting about 200 MiB per decode by default.
438	/// Size this budget against concurrent requests rather than one decode,
439	/// because thumbnail requests are not otherwise limited in number.
440	///
441	/// reloadable: yes
442	/// default: 50000000
443	/// legacy: media_thumbnail_max_pixels
444	#[serde(default = "default_max_pixels")]
445	pub max_pixels: u64,
446
447	/// Serves animated thumbnails when requested under
448	/// [MSC2705](https://github.com/matrix-org/matrix-spec-proposals/pull/2705).
449	///
450	/// A requesting client receives an animated GIF when the source has a
451	/// frame sequence and a still otherwise; clients that do not request
452	/// animation always receive a still. Encoding quantizes each frame with
453	/// its own palette and costs much more than a still, so frame count and
454	/// total pixel limits also bound the work. Disabling this produces still
455	/// PNG thumbnails only.
456	///
457	/// reloadable: yes
458	/// default: true
459	/// legacy: media_thumbnail_animated
460	#[serde(default = "true_fn")]
461	pub animated: bool,
462
463	/// Limits the number of frames in an animated thumbnail.
464	///
465	/// Longer sources are truncated into a shorter loop without notifying the
466	/// client, instead of being refused a thumbnail. Frames also share the
467	/// total `media.thumbnail.max_pixels` budget, so animation stops at
468	/// whichever limit is reached first. Both limits bound work that any
469	/// remote server can request.
470	///
471	/// reloadable: yes
472	/// default: 50
473	/// legacy: media_thumbnail_max_frames
474	#[serde(default = "default_max_frames")]
475	pub max_frames: usize,
476
477	/// Limits source jobs admitted for animated thumbnail generation.
478	///
479	/// A job acquires a slot before reading the full source and holds it
480	/// through source I/O, animated storage, and subsequent still or video
481	/// work until generation returns. A running blocking worker retains the
482	/// slot after request cancellation. Static images and videos also require
483	/// admission because their bytes determine whether animation work is
484	/// needed. Changes require a restart.
485	///
486	/// default: 4
487	/// legacy: media_thumbnail_animated_concurrency
488	#[serde(default = "default_animated_concurrency")]
489	pub animated_concurrency: usize,
490}
491
492/// URL previews
493///
494/// Link previews the server fetches on behalf of clients, built from the
495/// page's OpenGraph tags. Previews are off by default: with
496/// `domain_explicit_allowlist`, `domain_contains_allowlist` and
497/// `url_contains_allowlist` all empty, every preview request is refused
498/// and clients are told previews are disabled. To enable previews, list
499/// the hosts to allow.
500///
501/// Minimal example:
502///
503/// ```toml
504///     [global.media.url_preview]
505///     domain_explicit_allowlist = ["en.wikipedia.org", "github.com"]
506/// ```
507///
508/// Tips:
509/// - A host in `domain_explicit_denylist` is refused even when an
510///   allowlist admits it, except that `"*"` in any allowlist admits every
511///   URL before the denylist is consulted (and draws a startup warning).
512/// - An allowed URL is still refused when its host is an address in
513///   `network.http.ip_range_denylist`, or resolves to one.
514/// - `check_root_domain` strips only the first label of the host:
515///   `en.wikipedia.org` is also checked as `wikipedia.org`, but
516///   `en.m.wikipedia.org` only as `m.wikipedia.org`.
517#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
518#[derive(Clone, Debug, Deserialize)]
519#[config_example_generator(
520	filename = "tuwunel-example.toml",
521	section = "global.media.url_preview",
522	group = "true"
523)]
524pub struct UrlPreview {
525	/// Selects an optional source IP address or interface for URL preview
526	/// requests.
527	///
528	/// When unset, requests are not bound to a specific address or interface.
529	/// Interface names are supported only on Linux, Android, and Fuchsia;
530	/// other platforms can specify an IP address. Use `ip link show` to list
531	/// system interfaces.
532	///
533	/// example: `"eth0"` or `"1.2.3.4"`
534	/// default:
535	/// legacy: url_preview_bound_interface
536	#[serde(default, with = "either::serde_untagged_optional")]
537	pub bound_interface: Option<Either<IpAddr, String>>,
538
539	/// Allows URL preview requests to domains containing a listed string.
540	///
541	/// Matching is by containment rather than equality: "google.com" matches
542	/// both "https://google.com" and
543	/// "http://mymaliciousdomainexamplegoogle.com". A value of "*" allows all
544	/// URL previews. This exposes significant server attack surface and
545	/// requires understanding the risks.
546	///
547	/// reloadable: yes
548	/// default: []
549	/// legacy: url_preview_domain_contains_allowlist
550	#[serde(default)]
551	pub domain_contains_allowlist: Vec<String>,
552
553	/// Allows URL preview requests to explicitly listed domains.
554	///
555	/// Matching is exact rather than by containment: "google.com" matches
556	/// "https://google.com" and "http://google.com", but not
557	/// "https://mymaliciousdomainexamplegoogle.com". A value of "*" allows all
558	/// URL previews. This exposes significant server attack surface and
559	/// requires understanding the risks.
560	///
561	/// reloadable: yes
562	/// default: []
563	/// legacy: url_preview_domain_explicit_allowlist
564	#[serde(default)]
565	pub domain_explicit_allowlist: Vec<String>,
566
567	/// Rejects URL preview requests to explicitly listed domains.
568	///
569	/// Matching is exact rather than by containment: "google.com" matches
570	/// "https://google.com" and "http://google.com", but not
571	/// "https://mymaliciousdomainexamplegoogle.com". The denylist is checked
572	/// before the allowlists, unless an allowlist holds "*". A value of "*"
573	/// here has no effect.
574	///
575	/// reloadable: yes
576	/// default: []
577	/// legacy: url_preview_domain_explicit_denylist
578	#[serde(default)]
579	pub domain_explicit_denylist: Vec<String>,
580
581	/// Allows URL preview requests to URLs containing a listed string.
582	///
583	/// Matching is by containment rather than equality: "google.com" matches
584	/// "https://google.com/",
585	/// "https://google.com/url?q=https://mymaliciousdomainexample.com", and
586	/// "https://mymaliciousdomainexample.com/hi/google.com". A value of "*"
587	/// allows all URL previews. This exposes significant server attack surface
588	/// and requires understanding the risks.
589	///
590	/// reloadable: yes
591	/// default: []
592	/// legacy: url_preview_url_contains_allowlist
593	#[serde(default)]
594	pub url_contains_allowlist: Vec<String>,
595
596	/// Limits the body size read when fetching a URL preview page.
597	///
598	/// Accepts an integer byte count or an SI/IEC string such as "768 KiB". A
599	/// page whose OpenGraph tags fall beyond the limit produces an empty
600	/// preview, so pages beginning with large script blocks need a larger
601	/// budget.
602	///
603	/// reloadable: yes
604	/// default: 786432
605	/// legacy: url_preview_max_spider_size
606	#[serde(
607		default = "default_max_spider_size",
608		deserialize_with = "deserialize_bytesize_usize"
609	)]
610	pub max_spider_size: usize,
611
612	/// Limits each media item fetched or relayed for a URL preview.
613	///
614	/// This covers the og:image measurement fetch and lazy-media relay. Media
615	/// with an advertised length above the limit is not registered, and a
616	/// relay that would exceed it is refused. Accepts an integer byte count or
617	/// an SI/IEC string such as "50 MiB".
618	///
619	/// reloadable: yes
620	/// default: "50 MiB"
621	/// legacy: url_preview_max_media_size
622	#[serde(
623		default = "default_preview_max_size",
624		deserialize_with = "deserialize_bytesize_usize"
625	)]
626	pub max_media_size: usize,
627
628	/// Sets the lifetime in seconds of cached URL previews, including empty
629	/// previews.
630	///
631	/// Increasing this reduces requests to origins when room history is read
632	/// often, at the cost of serving OpenGraph metadata that may have changed.
633	/// A value of 0 fetches on every request. Raising it beyond seven days
634	/// takes effect at the next restart because the database applies its
635	/// retention floor when opened.
636	///
637	/// reloadable: yes
638	/// default: 86400
639	/// legacy: url_preview_cache_ttl
640	#[serde(default = "default_cache_ttl")]
641	pub cache_ttl: u64,
642
643	/// Checks the host again with its first label removed when no list admitted
644	/// it.
645	///
646	/// Only the explicit denylist and allowlist are consulted for the shortened
647	/// name, since a contains entry it holds already matched the full host.
648	/// One label is removed: with "wikipedia.org" in
649	/// `domain_explicit_allowlist`, "en.wikipedia.org" is admitted, while
650	/// "en.m.wikipedia.org" is checked only as "m.wikipedia.org" and refused.
651	///
652	/// reloadable: yes
653	/// legacy: url_preview_check_root_domain
654	#[serde(default)]
655	pub check_root_domain: bool,
656
657	/// Sets the User-Agent used to fetch preview pages and extract OpenGraph
658	/// tags.
659	///
660	/// When unset, the versioned server User-Agent is followed by "preview",
661	/// such as "Tuwunel/1.8.1 preview". Some origins serve OpenGraph tags only
662	/// to recognized preview crawlers and otherwise place them beyond
663	/// `media.url_preview.max_spider_size`.
664	///
665	/// reloadable: yes
666	/// default:
667	/// legacy: url_preview_user_agent
668	#[serde(default)]
669	pub user_agent: Option<String>,
670
671	/// Sets the User-Agent used to fetch and relay URL preview media files.
672	///
673	/// This covers og:image, og:video, og:audio, and direct links rather than
674	/// their containing pages. When unset, it falls back to
675	/// `media.url_preview.user_agent`, then the versioned server User-Agent.
676	///
677	/// reloadable: yes
678	/// default:
679	/// legacy: url_preview_media_user_agent
680	#[serde(default)]
681	pub media_user_agent: Option<String>,
682
683	/// Sets Accept-Language for URL preview page and media requests.
684	///
685	/// For example, "en-US,en;q=0.9" requests English from sites supporting
686	/// language negotiation, while sites choosing a language solely by IP may
687	/// ignore it. When unset, no Accept-Language header is sent. Changes
688	/// affect new requests; cached previews retain their language until
689	/// expiry.
690	///
691	/// reloadable: yes
692	/// default:
693	/// legacy: url_preview_accept_language
694	#[serde(default)]
695	pub accept_language: Option<String>,
696}
697
698/// Video thumbnails
699///
700/// The server decodes no video itself. To thumbnail a video it runs the
701/// external program named in `command`, such as `ffmpeg`, which must be
702/// installed where the server runs; the frame it writes is then
703/// thumbnailed under the limits of `[global.media.thumbnail]`. With
704/// `command` empty (the default), videos are served without a thumbnail.
705///
706/// Tips:
707/// - The published container images hold only the `tuwunel` binary and a
708///   CA bundle; add the program with a derived image or by mounting a
709///   statically linked build.
710/// - A systemd unit that filters out the `@ipc` syscalls must allow
711///   `pipe` and `pipe2` again (`SystemCallFilter=pipe pipe2`, as the
712///   packaged units do), or spawning the program fails.
713/// - A video whose extraction failed is not retried for five minutes, so
714///   test a corrected `command` with another video.
715/// - The config is refused when `timeout` is 0 or `concurrency` is outside
716///   1 to 1024.
717#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
718#[derive(Clone, Debug, Deserialize)]
719#[config_example_generator(
720	filename = "tuwunel-example.toml",
721	section = "global.media.video_thumbnail",
722	group = "true"
723)]
724pub struct VideoThumbnail {
725	/// Selects the program used to extract a still frame for videos uploaded
726	/// without a thumbnail.
727	///
728	/// We do not decode video internally; we scale and crop the extracted
729	/// frame like any other image, then cache an ordinary thumbnail. The list
730	/// is an argument vector with the program first and its arguments after
731	/// it, executed directly without a shell. Before each call, every argument
732	/// substitutes `{input}` with the temporary source-video path and
733	/// `{width}` and `{height}` with the requested dimensions. The program
734	/// writes one frame to standard output as PNG, JPEG, WebP, or GIF; an
735	/// empty list serves videos without thumbnails.
736	///
737	/// reloadable: yes
738	/// example: [
739	/// "ffmpeg", "-loglevel", "error", "-i", "{input}", "-vf", "thumbnail",
740	/// "-frames:v", "1", "-f", "image2pipe", "-c:v", "mjpeg", "pipe:1",
741	/// ]
742	///
743	/// default: []
744	/// legacy: media_video_thumbnail_command
745	#[serde(default)]
746	pub command: Vec<String>,
747
748	/// Limits the seconds a video thumbnail request can spend extracting a
749	/// frame.
750	///
751	/// One deadline covers waiting for a slot, staging the video, and running
752	/// the program, preventing queueing from multiplying the timeout. Expiry
753	/// kills the program and anything it spawned, then serves the video
754	/// without a thumbnail. Extraction requires a nonempty
755	/// `media.video_thumbnail.command`.
756	///
757	/// reloadable: yes
758	/// default: 30
759	/// legacy: media_video_thumbnail_timeout
760	#[serde(default = "default_timeout")]
761	pub timeout: u64,
762
763	/// Limits simultaneous video thumbnail extractions.
764	///
765	/// Video decoding costs much more than image scaling, so excess requests
766	/// wait for a slot instead of adding host load. Slots span video staging
767	/// through program exit, also limiting the number of staged videos.
768	/// Increase this when cores are available; changes require a restart. This
769	/// applies only when `media.video_thumbnail.command` is nonempty.
770	///
771	/// default: 1
772	/// legacy: media_video_thumbnail_concurrency
773	#[serde(default = "default_concurrency")]
774	pub concurrency: usize,
775
776	/// Limits the byte size of staged videos and extracted frames.
777	///
778	/// Oversized videos are served without thumbnails rather than staged, and
779	/// oversized frames are refused rather than decoded from truncated data.
780	/// Accepts an integer byte count or an SI/IEC string such as "128 MiB".
781	/// Extraction requires a nonempty `media.video_thumbnail.command`.
782	///
783	/// reloadable: yes
784	/// default: "128 MiB"
785	/// legacy: media_video_thumbnail_max_size
786	#[serde(
787		default = "default_max_size",
788		deserialize_with = "deserialize_bytesize_usize"
789	)]
790	pub max_size: usize,
791
792	/// Selects the directory for staging videos read by thumbnail programs.
793	///
794	/// Each running program has one file, removed when it exits. When unset, a
795	/// `tmp` subdirectory of the database path keeps large videos off the
796	/// memory-backed `/tmp` commonly provided by service managers. Files left
797	/// by a killed server are reclaimed at startup even when
798	/// `media.video_thumbnail.command` is empty. Extraction itself requires a
799	/// nonempty command.
800	///
801	/// reloadable: yes
802	/// example: "/var/tmp/tuwunel"
803	/// legacy: media_video_thumbnail_path
804	pub path: Option<PathBuf>,
805}
806
807impl Default for Media {
808	fn default() -> Self {
809		Self {
810			max_pending_uploads: default_max_pending_uploads(),
811			create_unused_expiration_time: default_create_unused_expiration_time(),
812			rc_create_per_second: default_rc_create_per_second(),
813			rc_create_burst_count: default_rc_create_burst_count(),
814			upload_min_free_space: default_upload_min_free_space(),
815			deny_framing: Default::default(),
816			deny_inline_styles: Default::default(),
817			allow_legacy: Default::default(),
818			request_legacy: Default::default(),
819			freeze_legacy: true_fn(),
820			startup_check: true_fn(),
821			compat_file_link: Default::default(),
822			prune_missing: Default::default(),
823			storage_providers: default_storage_providers(),
824			store_on_providers: Default::default(),
825			allow_redirect: Default::default(),
826			prevent_downloads_from: Default::default(),
827			import: Import::default(),
828			thumbnail: Thumbnail::default(),
829			url_preview: UrlPreview::default(),
830			video_thumbnail: VideoThumbnail::default(),
831		}
832	}
833}
834
835/// Reports whether new media is written to the named storage provider.
836///
837/// A provider qualifies only when media is read from it, and an empty
838/// `store_on_providers` list selects every such provider.
839#[implement(Media)]
840#[inline]
841#[must_use]
842pub fn writes_to(&self, provider: &str) -> bool {
843	self.reads_from(provider) && is_empty_or_contains(&self.store_on_providers, provider)
844}
845
846/// Reports whether media is read from the named storage provider.
847///
848/// An empty `storage_providers` list selects every provider.
849#[implement(Media)]
850#[inline]
851#[must_use]
852pub fn reads_from(&self, provider: &str) -> bool {
853	is_empty_or_contains(&self.storage_providers, provider)
854}
855
856impl Default for ImportConduit {
857	fn default() -> Self {
858		Self {
859			source_path: None,
860			directory_depth: default_directory_depth(),
861			directory_length: default_directory_length(),
862			source_provider: None,
863		}
864	}
865}
866
867impl Default for Thumbnail {
868	fn default() -> Self {
869		Self {
870			max_pixels: default_max_pixels(),
871			animated: true_fn(),
872			max_frames: default_max_frames(),
873			animated_concurrency: default_animated_concurrency(),
874		}
875	}
876}
877
878impl Default for UrlPreview {
879	fn default() -> Self {
880		Self {
881			bound_interface: Default::default(),
882			domain_contains_allowlist: Default::default(),
883			domain_explicit_allowlist: Default::default(),
884			domain_explicit_denylist: Default::default(),
885			url_contains_allowlist: Default::default(),
886			max_spider_size: default_max_spider_size(),
887			max_media_size: default_preview_max_size(),
888			cache_ttl: default_cache_ttl(),
889			check_root_domain: Default::default(),
890			user_agent: Default::default(),
891			media_user_agent: Default::default(),
892			accept_language: Default::default(),
893		}
894	}
895}
896
897impl Default for VideoThumbnail {
898	fn default() -> Self {
899		Self {
900			command: Default::default(),
901			timeout: default_timeout(),
902			concurrency: default_concurrency(),
903			max_size: default_max_size(),
904			path: None,
905		}
906	}
907}
908
909fn default_max_pending_uploads() -> usize { 5 }
910
911fn default_create_unused_expiration_time() -> u64 { 86400 }
912
913fn default_rc_create_per_second() -> u32 { 10 }
914
915fn default_rc_create_burst_count() -> u32 { 50 }
916
917fn default_upload_min_free_space() -> u64 { 1024 * 1024 * 1024 }
918
919fn default_storage_providers() -> BTreeSet<String> { ["media".to_owned()].into() }
920
921fn default_directory_depth() -> u8 { 2 }
922
923fn default_directory_length() -> u8 { 2 }
924
925fn default_max_pixels() -> u64 { 50_000_000 }
926
927fn default_max_frames() -> usize { 50 }
928
929fn default_animated_concurrency() -> usize { 4 }
930
931fn default_max_spider_size() -> usize {
932	768 * 1024 // 768 KiB
933}
934
935fn default_preview_max_size() -> usize {
936	50 * 1024 * 1024 // 50 MiB
937}
938
939fn default_cache_ttl() -> u64 { 60 * 60 * 24 }
940
941fn default_timeout() -> u64 { 30 }
942
943fn default_concurrency() -> usize { 1 }
944
945fn default_max_size() -> usize { 128 * 1024 * 1024 }