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 }