From 7a927aac59bad94111ef585dc9770bfc92280e6d Mon Sep 17 00:00:00 2001 From: DMRobertson Date: Tue, 21 Sep 2021 13:05:07 +0000 Subject: deploy: 9ffa787eb243c98a6ca1ecd9eac4a6b5dac2bef0 --- latest/development/cas.html | 2 +- latest/development/contributing_guide.html | 2 +- latest/development/database_schema.html | 2 +- latest/development/git.html | 2 +- .../development/internal_documentation/index.html | 2 +- latest/development/room-dag-concepts.html | 2 +- latest/development/saml.html | 2 +- latest/development/url_previews.html | 320 +++++++++++++++++++++ 8 files changed, 327 insertions(+), 7 deletions(-) create mode 100644 latest/development/url_previews.html (limited to 'latest/development') diff --git a/latest/development/cas.html b/latest/development/cas.html index aec4508389..940580dc80 100644 --- a/latest/development/cas.html +++ b/latest/development/cas.html @@ -99,7 +99,7 @@ diff --git a/latest/development/contributing_guide.html b/latest/development/contributing_guide.html index 72fb4f93d1..894a84b171 100644 --- a/latest/development/contributing_guide.html +++ b/latest/development/contributing_guide.html @@ -99,7 +99,7 @@ diff --git a/latest/development/database_schema.html b/latest/development/database_schema.html index f2df222a04..9e58553b90 100644 --- a/latest/development/database_schema.html +++ b/latest/development/database_schema.html @@ -99,7 +99,7 @@ diff --git a/latest/development/git.html b/latest/development/git.html index c6475334be..f2438420e5 100644 --- a/latest/development/git.html +++ b/latest/development/git.html @@ -99,7 +99,7 @@ diff --git a/latest/development/internal_documentation/index.html b/latest/development/internal_documentation/index.html index ef86d89b67..bbd12e4cc4 100644 --- a/latest/development/internal_documentation/index.html +++ b/latest/development/internal_documentation/index.html @@ -99,7 +99,7 @@ diff --git a/latest/development/room-dag-concepts.html b/latest/development/room-dag-concepts.html index 00c45dda53..c389127ac6 100644 --- a/latest/development/room-dag-concepts.html +++ b/latest/development/room-dag-concepts.html @@ -99,7 +99,7 @@ diff --git a/latest/development/saml.html b/latest/development/saml.html index 25f5d22d3a..49686449c4 100644 --- a/latest/development/saml.html +++ b/latest/development/saml.html @@ -99,7 +99,7 @@ diff --git a/latest/development/url_previews.html b/latest/development/url_previews.html new file mode 100644 index 0000000000..7189a53575 --- /dev/null +++ b/latest/development/url_previews.html @@ -0,0 +1,320 @@ + + + + + + URL Previews - Synapse + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + + + + +
+
+ +
+ +
+ +

URL Previews

+

The GET /_matrix/media/r0/preview_url endpoint provides a generic preview API +for URLs which outputs Open Graph responses (with some Matrix +specific additions).

+

This does have trade-offs compared to other designs:

+
    +
  • Pros: +
      +
    • Simple and flexible; can be used by any clients at any point
      • +
    +
    • +
  • Cons: +
      +
    • If each homeserver provides one of these independently, all the HSes in a +room may needlessly DoS the target URI
      • +
    • The URL metadata must be stored somewhere, rather than just using Matrix +itself to store the media.
      • +
    • Matrix cannot be used to distribute the metadata between homeservers.
      • +
    +
    • +
+

When Synapse is asked to preview a URL it does the following:

+
    +
  1. Checks against a URL blacklist (defined as url_preview_url_blacklist in the +config).
    2. +
  2. Checks the in-memory cache by URLs and returns the result if it exists. (This +is also used to de-duplicate processing of multiple in-flight requests at once.)
    3. +
  3. Kicks off a background process to generate a preview: +
      +
    1. Checks the database cache by URL and timestamp and returns the result if it +has not expired and was successful (a 2xx return code).
      2. +
    2. Checks if the URL matches an oEmbed pattern. If it does, fetch the oEmbed +response. If this is an image, replace the URL to fetch and continue. If +if it is HTML content, use the HTML as the document and continue.
      3. +
    3. If it doesn't match an oEmbed pattern, downloads the URL and stores it +into a file via the media storage provider and saves the local media +metadata.
      4. +
    4. If the media is an image: +
        +
      1. Generates thumbnails.
        2. +
      2. Generates an Open Graph response based on image properties.
        3. +
      +
      5. +
    5. If the media is HTML: +
        +
      1. Decodes the HTML via the stored file.
        2. +
      2. Generates an Open Graph response from the HTML.
        3. +
      3. If an image exists in the Open Graph response: +
          +
        1. Downloads the URL and stores it into a file via the media storage +provider and saves the local media metadata.
          2. +
        2. Generates thumbnails.
          3. +
        3. Updates the Open Graph response based on image properties.
          4. +
        +
        4. +
      +
      6. +
    6. Stores the result in the database cache.
      7. +
    +
    4. +
  4. Returns the result.
    5. +
+

The in-memory cache expires after 1 hour.

+

Expired entries in the database cache (and their associated media files) are +deleted every 10 seconds. The default expiration time is 1 hour from download.

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file -- cgit 1.5.1