Struct Service 

pub struct Service {
    pub(crate) db: Data,
    services: Arc<OnceServices>,
    url_preview_mutex: MutexMap<String, ()>,
    federation_mutex: MutexMap<String, ()>,
    mxc_state: MXCState,
    animated_thumbnail_slots: Arc<Semaphore>,
    video_thumbnail_slots: Semaphore,
    video_thumbnail_failures: Mutex<LruCache<String, Instant>>,
}

Fields

db: Data

services: Arc<OnceServices>

url_preview_mutex: MutexMap<String, ()>

federation_mutex: MutexMap<String, ()>

mxc_state: MXCState

animated_thumbnail_slots: Arc<Semaphore>

video_thumbnail_slots: Semaphore

video_thumbnail_failures: Mutex<LruCache<String, Instant>>

Implementations

impl Service

pub async fn get_url_preview(&self, url: &Url) -> Result<UrlPreviewData>

impl Service

pub async fn request_url_preview(&self, url: &Url) -> Result<UrlPreviewData>

impl Service

fn preview_get(&self, url: &Url, agent: Agent) -> RequestBuilder

Build a preview request through the preview client, carrying the headers preview_headers applies.

impl Service

pub(super) fn preview_headers( &self, request: RequestBuilder, url: &Url, agent: Agent, ) -> RequestBuilder

Apply the configured User-Agent, Accept-Language, and any origin-specific headers to a preview request.

Headers are read per request rather than baked into the client, so a configuration reload takes effect without restarting the server. The configuration is bound once so the header options are read through a single handle.

impl Service

fn check_remote_addr(&self, response: &Response) -> Result

Screen a preview response’s peer address against the CIDR denylist.

A missing peer address cannot be screened, so it fails closed.

impl Service

async fn oembed_recover( &self, url: &Url, data: UrlPreviewData, ) -> UrlPreviewData

Recover a preview from the origin’s oEmbed endpoint when the page yielded nothing usable.

Some origins serve their <head> metadata only to an agent they recognise as a link-preview crawler, while answering oEmbed for anyone. A page that parsed to nothing is therefore worth one much smaller second request, and the original preview stands if that request fails too.

impl Service

async fn oembed_preview( &self, endpoint: &Url, page: &Url, ) -> Result<UrlPreviewData>

Fetch an oEmbed document and render it as a preview.

The document names a thumbnail rather than carrying one, so the image is measured and staged through the same path an og:image takes.

impl Service

async fn oembed_image(&self, thumbnail_url: Option<&str>) -> UrlPreviewData

Measure an oEmbed thumbnail, yielding an empty preview when it is absent or unusable.

A thumbnail failure must not cost the textual preview the document has already provided.

impl Service

async fn preview_image(&self, image_url: &Url) -> Result<UrlPreviewData>

Fetch and measure a preview image, keeping the textual preview when the origin refuses it.

The measurement is a media fetch: it carries the media agent, or the origin could serve the measurement different content than it serves the relayed mxc.

impl Service

pub async fn download_image(&self, response: Response) -> Result<UrlPreviewData>

Download an image for URL preview metadata.

When URL previews are enabled, the image is staged for lazy media retrieval; otherwise this returns the feature-disabled error.

impl Service

async fn media_response(&self, url: &Url) -> Result<Response>

Fetch a URL with the media client, applying the same address and status screening as the page fetch. Direct preview media is measured and registered from the media client’s response so it matches what the relay will serve.

impl Service

async fn media_refetch( &self, url: &Url, response: Response, via_media_client: bool, ) -> Result<Response>

Replace a page-client response with the media client’s for a direct media URL. When no distinct media agent is configured the two clients are identical and the original response is used as-is, avoiding a second request.

impl Service

fn register_lazy_media(&self, url: &str) -> String

Mint a local mxc:// URI that resolves to url on first download (see Service::fetch_lazy_media), keeping preview generation independent of the underlying file size while routing clients through this server.

impl Service

fn queue_lazy_media(&self, txn: &mut Txn, url: &str) -> String

impl Service

fn mint_lazy_media(&self) -> String

impl Service

pub async fn download_video(&self, response: Response) -> Result<UrlPreviewData>

impl Service

pub async fn download_audio(&self, response: Response) -> Result<UrlPreviewData>

impl Service

async fn download_html( &self, url: &Url, response: Response, ) -> Result<UrlPreviewData>

impl Service

fn lazy_media( &self, page: &Url, obj: &OpengraphObject, class: &str, ) -> Option<String>

Mint an mxc:// URI for a page’s declared media, or nothing when it is not relayable.

The URL is recorded rather than fetched, so a page naming a large video costs the preview request no bandwidth; it is fetched and checked only once a client asks for the resulting URI. Screening IP literals here as well keeps a preview from handing out a URI that the same check at relay time is guaranteed to refuse.

impl Service

pub(super) fn check_url_host(&self, url: &Url) -> Result

impl Service

pub fn url_preview_allowed(&self, url: &Url) -> bool

impl Service

pub async fn fetch_remote_thumbnail( &self, mxc: &Mxc<'_>, server: Option<&ServerName>, timeout_ms: Duration, dim: &Dim, animate: Animate, ) -> Result<Fetched>

Fetches a thumbnail at this dimension from the origin server.

The authenticated endpoint is asked first, falling back to the legacy one only where the peer answers no such media and this server is configured to ask. What the walk filing the answer settled travels back with it, so a caller deciding whether the picture may be served reads no bytes again.

impl Service

pub async fn fetch_remote_content( &self, mxc: &Mxc<'_>, server: Option<&ServerName>, timeout_ms: Duration, ) -> Result<Fetched>

Fetches the original file from the origin server.

The authenticated endpoint is asked first, falling back to the legacy one only where the peer answers no such media and this server is configured to ask. What the walk filing the answer settled travels back with it, so a caller deciding whether the picture may be served reads no bytes again.

impl Service

async fn fetch_thumbnail_authenticated( &self, mxc: &Mxc<'_>, server: Option<&ServerName>, timeout_ms: Duration, dim: &Dim, animate: Animate, ) -> Result<Fetched>

impl Service

async fn fetch_content_authenticated( &self, mxc: &Mxc<'_>, server: Option<&ServerName>, timeout_ms: Duration, ) -> Result<Fetched>

impl Service

async fn fetch_thumbnail_unauthenticated( &self, mxc: &Mxc<'_>, server: Option<&ServerName>, timeout_ms: Duration, dim: &Dim, animate: Animate, ) -> Result<Fetched>

impl Service

async fn fetch_content_unauthenticated( &self, mxc: &Mxc<'_>, server: Option<&ServerName>, timeout_ms: Duration, ) -> Result<Fetched>

impl Service

async fn handle_thumbnail_file( &self, mxc: &Mxc<'_>, dim: &Dim, content: Content, ) -> Result<Fetched>

impl Service

async fn handle_content_file( &self, mxc: &Mxc<'_>, content: Content, ) -> Result<Fetched>

impl Service

async fn handle_location( &self, mxc: &Mxc<'_>, location: &str, ) -> Result<Fetched>

impl Service

pub(super) async fn location_request( &self, fetch: Fetch, location: &str, limit: usize, ) -> Result<Media>

impl Service

async fn federation_request<Request>( &self, mxc: &Mxc<'_>, server: Option<&ServerName>, request: Request, ) -> Result<Request::IncomingResponse>

where Request: OutgoingRequest + Send + Debug, Request::Authentication: FedAuth, Request::PathBuilder: FedPath,

impl Service

pub async fn fetch_remote_thumbnail_legacy( &self, mxc: &Mxc<'_>, timeout_ms: Duration, dim: &Dim, animate: Animate, ) -> Result<Media>

Fetches a thumbnail from the origin server over the legacy media API.

The dimension the origin is asked for is the dimension its answer is filed under, and every later lookup normalizes before it seeks, so the two have to agree or nothing cached on one request is found on the next. A request too large for any thumbnail size normalizes to the original file, which is fetched rather than asked for at a dimension that is not a size.

impl Service

pub async fn fetch_remote_content_legacy( &self, mxc: &Mxc<'_>, allow_redirect: bool, timeout_ms: Duration, ) -> Result<Response, Error>

impl Service

fn check_fetch_authorized(&self, mxc: &Mxc<'_>) -> Result

impl Service

fn check_legacy_freeze(&self) -> Result

impl Service

pub(super) async fn store_animated( &self, mxc: &Mxc<'_>, dim: &Dim, source: Bytes, admission: OwnedSemaphorePermit, ) -> Result<Output>

Encode this picture’s frames as an animated GIF thumbnail and store it.

Quantization runs per frame on a palette of its own, which is far more work than a still costs, so the encode is handed to a blocking worker rather than run on the async runtime. A source whose frames will not decode answers an error and the caller falls through to the still it would have produced.

impl Service

pub(super) fn decode_still(&self, bytes: &[u8]) -> Result<DynamicImage>

Decodes a picture that may not be served in the state it is held in.

Serving it is what the request forbade, so a decode that fails leaves nothing answerable and the caller has no fallback to offer.

impl Service

pub(in media) async fn store_still( &self, mxc: &Mxc<'_>, dim: &Dim, animated: Media, ) -> Result<Media>

Re-encode a fetched picture as a still thumbnail and store it.

A peer that ignores the parameter answers a cold fetch with animation, and this repairs it on the way out rather than one request later. The cached row takes its own path, which already holds the picture.

impl Service

pub(super) async fn get_thumbnail_generate( &self, mxc: &Mxc<'_>, dim: &Dim, animate: Animate, data: Metadata, ) -> Result<Media>

Generate a thumbnail.

A source that animates yields both variants here rather than the one this request asked for. Generation runs only on a lookup miss, and the row it stores is what stops the next miss, so a variant left ungenerated would wait on a miss that the other variant has already made impossible.

impl Service

pub(super) async fn store_thumbnail( &self, mxc: &Mxc<'_>, dim: &Dim, image: DynamicImage, ) -> Result<Media>

Encode a still PNG thumbnail at these dimensions and store it.

The generate path and the still-repair path share this, so a given size carries one content type and one disposition whichever produced it.

impl Service

pub(super) async fn store_encoded( &self, mxc: &Mxc<'_>, dim: &Dim, content: Vec<u8>, content_type: &str, filename: &str, ) -> Result<Media>

Store an encoded thumbnail under the type and name it carries.

Both encoders end here, so a stored thumbnail is disposed inline under the name the media repository specification asks of one whether or not the original arrived with a name of its own.

impl Service

pub(super) fn decode(&self, bytes: &[u8]) -> Result<DynamicImage>

Decode a picture whose header declares no more than the configured pixel count.

The dimensions are checked before any decoder allocates, since Limits enforces only a byte budget and leaves a decoder free to ignore it.

impl Service

pub async fn upload_thumbnail( &self, mxc: &Mxc<'_>, content_disposition: Option<&ContentDisposition>, content_type: Option<&str>, dim: &Dim, file: &[u8], ) -> Result

Uploads or replaces a file thumbnail.

Metadata is written first, then the supplied bytes replace the stored media body for the requested dimensions.

pub async fn get_or_fetch_thumbnail( &self, mxc: &Mxc<'_>, dim: &Dim, animate: Animate, timeout_ms: Duration, user: &UserId, ) -> Result<Media>

Answers a thumbnail request, fetching from the peer when it is remote.

The dimension a fetch asks the peer for is the dimension the answer is filed under, and every later lookup seeks the normalized one, so the three have to agree or nothing found on one request is found on the next. Past every bucket there is no dimension to ask at, and the request names the original file instead.

pub fn get_thumbnail<'a>( &'a self, __arg1: &'a Mxc<'_>, __arg2: &'a Dim, __arg3: Animate, __arg4: Option<Duration>, ) -> Pin<Box<dyn Future<Output = Result<Media>> + Send + 'a>>

Downloads a thumbnail, waiting for a pending upload when requested.

The supplied duration bounds that wait. The future is boxed because the still-repair path pulls the thumbnailer into it, and inlining that into every caller overflows the layout depth limit in the federation handler.

async fn __get_thumbnail<'a>( &'a self, mxc: &'a Mxc<'_>, dim: &'a Dim, animate: Animate, timeout_duration: Option<Duration>, ) -> Result<Media>

pub async fn get_stored_thumbnail( &self, mxc: &Mxc<'_>, dim: &Dim, animate: Animate, ) -> Result<Media>

Downloads a stored or generated thumbnail.

Requests normalize to a bounded storage bucket. An existing variant is returned directly; a missing variant is generated from the original or answered from promoted storage when the original row is absent.

impl Service

fn answer_original<'a>( &'a self, __arg1: &'a Mxc<'_>, __arg2: Animate, ) -> Pin<Box<dyn Future<Output = Result<Media>> + Send + 'a>>

Answers a request past every bucket, which names the original file.

The original’s own row is keyed at the sentinel, where there is no size to re-encode at, so a picture the request will not accept stands in at its own dimensions. Those are the largest a still may carry without upscaling, so the stand-in covers any request the original itself covers and is the best available where it does not.

The future is not inlined: this branch reaches the thumbnailer, and folding that into every caller overflows the layout depth limit.

async fn __answer_original<'a>( &'a self, mxc: &'a Mxc<'_>, animate: Animate, ) -> Result<Media>

impl Service

pub(super) async fn original_metadata(&self, mxc: &Mxc<'_>) -> Result<Metadata>

Metadata for the original file, which every thumbnail is derived from.

Its row is keyed at the sentinel dimension, and nothing is withheld from this lookup: the row is the original rather than a variant of it.

impl Service

async fn answer_promoted( &self, mxc: &Mxc<'_>, animate: Animate, ) -> Result<Media>

Answers from stored media when no metadata row names the original.

The original may be lazy preview media promoted on this very request, which leaves no row behind, and only a picture is worth serving in a thumbnail’s place. No row having named it, the request’s own preference is the only gate it passes, so the picture is read here as it is anywhere else.

impl Service

pub(super) async fn fetch_bytes(&self, key: &[u8]) -> Result<Bytes>

The stored bytes for a thumbnail row, from the first provider holding them.

Returning the shared Bytes spares a caller that only reads the picture the Vec copy Media would force on it.

impl Service

async fn answer_stored( &self, mxc: &Mxc<'_>, dim: &Dim, animate: Animate, data: Metadata, ) -> Result<Media>

Answers a request from a stored row, re-deriving a still if it animates.

The type a row is stored under is whatever produced it claimed, and a peer is free to claim wrongly, so the picture itself decides once it is in hand. A row that may not answer is re-encoded and the still left behind for the next request.

impl Service

pub(super) async fn video_frame( &self, mxc: &Mxc<'_>, dim: &Dim, media: &Media, ) -> Option<Vec<u8>>

Still frame standing in for a video, or None when the media is not a video, no program is configured, or extraction failed.

impl Service

fn failed_recently(&self, mxc: &Mxc<'_>) -> bool

Whether this video failed within the cooldown, where trying again would spend a slot to reach the same failure.

impl Service

pub(super) fn remember_failure(&self, mxc: &Mxc<'_>)

impl Service

async fn extract_frame( &self, mxc: &Mxc<'_>, dim: &Dim, content: &[u8], ) -> Result<Vec<u8>>

impl Service

pub async fn create_pending( &self, mxc: &Mxc<'_>, user: &UserId, unused_expires_at: u64, ) -> Result

Create a pending media upload ID.

pub async fn upload_pending( &self, mxc: &Mxc<'_>, user: &UserId, content_disposition: Option<&ContentDisposition>, content_type: Option<&str>, file: &[u8], ) -> Result

Uploads content to a pending media ID.

pub async fn create( &self, mxc: &Mxc<'_>, user: Option<&UserId>, content_disposition: Option<&ContentDisposition>, content_type: Option<&str>, file: &[u8], ) -> Result<bool>

Uploads a file and reports whether its own bytes carry a sequence.

The declared type is whoever uploaded it saying so, and a picture that animates is stored under the type its own container names instead. That is the only record of whether the media animates that a later lookup can read without fetching the whole of it. The disposition is left as the caller computed it, so a file already bound for download stays there.

pub async fn delete(&self, mxc: &Mxc<'_>) -> Result

Deletes a file in the database and from the media directory via an MXC

pub async fn delete_from_user(&self, user: &UserId) -> Result<usize>

Deletes all media by the specified user

currently, this is only practical for local users

pub async fn get_or_fetch( &self, mxc: &Mxc<'_>, timeout_ms: Duration, ) -> Result<Media>

Get file from local storage or make a federation request if it originates remotely.

pub async fn get( &self, mxc: &Mxc<'_>, timeout: Option<Duration>, ) -> Result<Media>

Get file from local storage while waiting up to a timeout_ms if it is pending.

pub async fn get_stored(&self, mxc: &Mxc<'_>) -> Result<Media>

Get file from local storage.

A metadata miss falls through to the lazy-media path, which serializes on a per-mxc mutex and fetches the origin once.

async fn fetch_lazy_media(&self, mxc: &Mxc<'_>) -> Result<Media>

Resolve lazy URL-preview media on first download, promoting the staged or freshly-fetched bytes into the media store so the origin is fetched at most once per item.

pub async fn redirect_url( &self, mxc: &Mxc<'_>, dim: &Dim, animate: Animate, ) -> Result<Option<Url>>

Presigned redirect URL for locally-stored media (MSC3860).

Returns the first configured provider’s signed URL for the object, or None when redirects are disabled, the media is unknown, or no provider can presign it (filesystem-only media). A stored file that animates also answers None to a request forbidding animation, since handing over the object as it stands cannot re-encode it.

pub async fn get_all_mxcs(&self) -> Result<Vec<OwnedMxcUri>>

Gets all the MXC URIs in our media database

pub async fn user_media(&self, user: &UserId) -> Result<Vec<UserMediaEntry>>

Every media item uploaded by a local user, carrying the fields tuwunel can derive: content type, upload name, byte length and modification time from storage-provider object metadata. Untracked columns (last-access, quarantine, url-cache) are not represented.

pub async fn media_entry(&self, mxc: &Mxc<'_>) -> Option<UserMediaEntry>

Derivable metadata for the single media item at the given MXC, with the uploading local user resolved from the uploader index when present.

async fn user_media_entry( &self, user: Option<&UserId>, mxc: OwnedMxcUri, ) -> Option<UserMediaEntry>

pub fn upload_stats(&self) -> impl Stream<Item = UploadStat> + Send + '_

Uploader, byte length and storage modification time of every media item uploaded by a local user, one row per upload; media missing from every storage provider are skipped.

pub async fn delete_by_date_size( &self, before_ts: u64, size_gt: u64, keep_profiles: bool, ) -> Result<Vec<OwnedMxcUri>>

Deletes local media older than before_ts (by storage-provider mtime) and strictly larger than size_gt bytes, sparing profile and room-avatar media when keep_profiles. Returns the deleted MXCs, empty when none match. Quarantine and protection flags are not tracked, so no media is spared on those grounds.

async fn avatar_mxcs(&self) -> HashSet<OwnedMxcUri>

The MXCs of every local user’s profile avatar and every room’s avatar, the spare-set honoured by keep_profiles.

fn is_local(&self, mxc: &OwnedMxcUri) -> bool

async fn head_meta(&self, key: &[u8]) -> Option<ObjectMeta>

First storage provider’s object metadata for the media stored under key (byte length and modification time), or None when no provider holds it.

pub async fn delete_range( &self, time: SystemTime, older_than: bool, newer_than: bool, yes_i_want_to_delete_local_media: bool, ) -> Result<usize>

Deletes all media files before or after the given time. Returns a usize with the number of media files deleted.

pub async fn create_media_dir(&self) -> Result

async fn remove_media_file(&self, key: &[u8]) -> Result

async fn create_media_file(&self, key: &[u8], file: &[u8]) -> Result

fn storage_providers(&self) -> impl Iterator<Item = &Arc<Provider>> + Send + '_

pub async fn get_metadata(&self, mxc: &Mxc<'_>) -> Option<Metadata>

pub fn get_media_path_sha256(&self, key: &[u8]) -> PathBuf

pub fn get_media_name_sha256(&self, key: &[u8]) -> String

new SHA256 file name media function. requires database migrated. uses SHA256 hash of the base64 key as the file name

pub fn get_media_path_b64(&self, key: &[u8]) -> PathBuf

old base64 file name media function This is the old version of get_media_path_sha256 that uses the full base64 key as the filename.

pub fn get_media_dir(&self) -> PathBuf

Trait Implementations

impl Service for Service

fn build(args: &Args<'_>) -> Result<Arc<Self>>

Implement the construction of the service instance. Services are generally singletons so expect this to only be called once for a service type. Note that it may be called again after a server reload, but the prior instance will have been dropped first. Failure will shutdown the server with an error.

fn name(&self) -> &str

Return the name of the service. i.e. crate::service::make_name(std::module_path!())

fn worker<'async_trait>( self: Arc<Self>, ) -> Pin<Box<dyn Future<Output = Result> + Send + 'async_trait>>

where Self: 'async_trait,

Implement the service’s worker loop. The service manager spawns a task and calls this function after all services have been built.

fn interrupt<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Interrupt the service. This is sent to initiate a graceful shutdown. The service worker should return from its work loop.

fn clear_cache<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Clear any caches or similar runtime state.

fn memory_usage<'life0, 'life1, 'async_trait>( &'life0 self, _out: &'life1 mut (dyn Write + Send), ) -> Pin<Box<dyn Future<Output = Result> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Memory usage report in a markdown string.

fn unconstrained(&self) -> bool

Return true if the service worker opts out of the tokio cooperative budgeting. This can reduce tail latency at the risk of event loop starvation.