2021-06-03 16:21:02 +00:00
<!DOCTYPE HTML>
< html lang = "en" class = "sidebar-visible no-js light" >
< head >
<!-- Book generated using mdBook -->
< meta charset = "UTF-8" >
< title > User Directory - Synapse< / title >
<!-- Custom HTML head -->
< meta content = "text/html; charset=utf-8" http-equiv = "Content-Type" >
< meta name = "description" content = "" >
< meta name = "viewport" content = "width=device-width, initial-scale=1" >
< meta name = "theme-color" content = "#ffffff" / >
< link rel = "icon" href = "favicon.svg" >
< link rel = "shortcut icon" href = "favicon.png" >
< link rel = "stylesheet" href = "css/variables.css" >
< link rel = "stylesheet" href = "css/general.css" >
< link rel = "stylesheet" href = "css/chrome.css" >
< link rel = "stylesheet" href = "css/print.css" media = "print" >
<!-- Fonts -->
< link rel = "stylesheet" href = "FontAwesome/css/font-awesome.css" >
< link rel = "stylesheet" href = "fonts/fonts.css" >
<!-- Highlight.js Stylesheets -->
< link rel = "stylesheet" href = "highlight.css" >
< link rel = "stylesheet" href = "tomorrow-night.css" >
< link rel = "stylesheet" href = "ayu-highlight.css" >
<!-- Custom theme stylesheets -->
< link rel = "stylesheet" href = "docs/website_files/table-of-contents.css" >
< link rel = "stylesheet" href = "docs/website_files/remove-nav-buttons.css" >
< link rel = "stylesheet" href = "docs/website_files/indent-section-headers.css" >
2023-12-11 14:20:01 +00:00
< link rel = "stylesheet" href = "docs/website_files/version-picker.css" >
2021-06-03 16:21:02 +00:00
< / head >
< body >
<!-- Provide site root to javascript -->
< script type = "text/javascript" >
var path_to_root = "";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
< / script >
<!-- Work around some values being stored in localStorage wrapped in quotes -->
< script type = "text/javascript" >
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') & & theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') & & sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
< / script >
<!-- Set the theme before any content is loaded, prevents flash -->
< script type = "text/javascript" >
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
< / script >
<!-- Hide / unhide sidebar before it is displayed -->
< script type = "text/javascript" >
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
< / script >
< nav id = "sidebar" class = "sidebar" aria-label = "Table of contents" >
< div class = "sidebar-scrollbox" >
2023-10-27 09:05:11 +00:00
< ol class = "chapter" > < li class = "chapter-item expanded affix " > < li class = "part-title" > Introduction< / li > < li class = "chapter-item expanded " > < a href = "welcome_and_overview.html" > Welcome and Overview< / a > < / li > < li class = "chapter-item expanded affix " > < li class = "part-title" > Setup< / li > < li class = "chapter-item expanded " > < a href = "setup/installation.html" > Installation< / a > < / li > < li class = "chapter-item expanded " > < a href = "postgres.html" > Using Postgres< / a > < / li > < li class = "chapter-item expanded " > < a href = "reverse_proxy.html" > Configuring a Reverse Proxy< / a > < / li > < li class = "chapter-item expanded " > < a href = "setup/forward_proxy.html" > Configuring a Forward/Outbound Proxy< / a > < / li > < li class = "chapter-item expanded " > < a href = "turn-howto.html" > Configuring a Turn Server< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "setup/turn/coturn.html" > coturn TURN server< / a > < / li > < li class = "chapter-item expanded " > < a href = "setup/turn/eturnal.html" > eturnal TURN server< / a > < / li > < / ol > < / li > < li class = "chapter-item expanded " > < a href = "delegate.html" > Delegation< / a > < / li > < li class = "chapter-item expanded affix " > < li class = "part-title" > Upgrading< / li > < li class = "chapter-item expanded " > < a href = "upgrade.html" > Upgrading between Synapse Versions< / a > < / li > < li class = "chapter-item expanded affix " > < li class = "part-title" > Usage< / li > < li class = "chapter-item expanded " > < a href = "federate.html" > Federation< / a > < / li > < li class = "chapter-item expanded " > < a href = "usage/configuration/index.html" > Configuration< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "usage/configuration/config_documentation.html" > Configuration Manual< / a > < / li > < li class = "chapter-item expanded " > < a href = "usage/configuration/homeserver_sample_config.html" > Homeserver Sample Config File< / a > < / li > < li class = "chapter-item expanded " > < a href = "usage/configuration/logging_sample_config.html" > Logging Sample Config File< / a > < / li > < li class = "chapter-item expanded " > < a href = "structured_logging.html" > Structured Logging< / a > < / li > < li class = "chapter-item expanded " > < a href = "templates.html" > Templates< / a > < / li > < li class = "chapter-item expanded " > < a href = "usage/configuration/user_authentication/index.html" > User Authentication< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "usage/configuration/user_authentication/single_sign_on/index.html" > Single-Sign On< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "openid.html" > OpenID Connect< / a > < / li > < li class = "chapter-item expanded " > < a href = "usage/configuration/user_authentication/single_sign_on/saml.html" > SAML< / a > < / li > < li class = "chapter-item expanded " > < a href = "usage/configuration/user_authentication/single_sign_on/cas.html" > CAS< / a > < / li > < li class = "chapter-item expanded " > < a href = "sso_mapping_providers.html" > SSO Mapping Providers< / a > < / li > < / ol > < / li > < li class = "chapter-item expanded " > < a href = "password_auth_providers.html" > Password Auth Providers< / a > < / li > < li class = "chapter-item expanded " > < a href = "jwt.html" > JSON Web Tokens< / a > < / li > < li class = "chapter-item expanded " > < a href = "usage/configuration/user_authentication/refresh_tokens.html" > Refresh Tokens< / a > < / li > < / ol > < / li > < li class = "chapter-item expanded " > < a href = "CAPTCHA_SETUP.html" > Registration Captcha< / a > < / li > < li class = "chapter-item expanded " > < a href = "application_services.html" > Application Services< / a > < / li > < li class = "chapter-item expanded " > < a href = "server_notices.html" > Server Notices< / a > < / li > < li class = "chapter-item expanded " > < a href = "consent_tracking.html" > Consent Tracking< / a > < / li > < li class = "chapter-item expanded " > < a href = "user_directory.html" class = "active" > User Directory< / a > < / li > < li class = "chapter-item expanded " > < a href = "message_retention_policies.html" > Message Retention Policies< / a > < / li > < li class = "chapter-item expanded " > < a href = "modules/index.html" > Pluggable Modules< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "modules/writing_a_module.html" > Writing a module< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "modules/spam_checker_callbacks.html" > Spam checker callbacks< / a > < / li > < li class
2021-06-03 16:21:02 +00:00
< / div >
< div id = "sidebar-resize-handle" class = "sidebar-resize-handle" > < / div >
< / nav >
< div id = "page-wrapper" class = "page-wrapper" >
< div class = "page" >
< div id = "menu-bar-hover-placeholder" > < / div >
< div id = "menu-bar" class = "menu-bar sticky bordered" >
< div class = "left-buttons" >
< button id = "sidebar-toggle" class = "icon-button" type = "button" title = "Toggle Table of Contents" aria-label = "Toggle Table of Contents" aria-controls = "sidebar" >
< i class = "fa fa-bars" > < / i >
< / button >
< button id = "theme-toggle" class = "icon-button" type = "button" title = "Change theme" aria-label = "Change theme" aria-haspopup = "true" aria-expanded = "false" aria-controls = "theme-list" >
< i class = "fa fa-paint-brush" > < / i >
< / button >
< ul id = "theme-list" class = "theme-popup" aria-label = "Themes" role = "menu" >
< li role = "none" > < button role = "menuitem" class = "theme" id = "light" > Light (default)< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "rust" > Rust< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "coal" > Coal< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "navy" > Navy< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "ayu" > Ayu< / button > < / li >
< / ul >
< button id = "search-toggle" class = "icon-button" type = "button" title = "Search. (Shortkey: s)" aria-label = "Toggle Searchbar" aria-expanded = "false" aria-keyshortcuts = "S" aria-controls = "searchbar" >
< i class = "fa fa-search" > < / i >
< / button >
2023-12-11 14:20:01 +00:00
< div class = "version-picker" >
< div class = "dropdown" >
< div class = "select" >
< span > < / span >
< i class = "fa fa-chevron-down" > < / i >
< / div >
< input type = "hidden" name = "version" >
< ul class = "dropdown-menu" >
<!-- Versions will be added dynamically in version - picker.js -->
< / ul >
< / div >
< / div >
2021-06-03 16:21:02 +00:00
< / div >
< h1 class = "menu-title" > Synapse< / h1 >
< div class = "right-buttons" >
< a href = "print.html" title = "Print this book" aria-label = "Print this book" >
< i id = "print-button" class = "fa fa-print" > < / i >
< / a >
2023-12-13 15:42:43 +00:00
< a href = "https://github.com/element-hq/synapse" title = "Git repository" aria-label = "Git repository" >
2021-06-03 16:21:02 +00:00
< i id = "git-repository-button" class = "fa fa-github" > < / i >
< / a >
2023-12-13 15:42:43 +00:00
< a href = "https://github.com/element-hq/synapse/edit/develop/docs/user_directory.md" title = "Suggest an edit" aria-label = "Suggest an edit" >
2021-06-03 16:21:02 +00:00
< i id = "git-edit-button" class = "fa fa-edit" > < / i >
< / a >
< / div >
< / div >
< div id = "search-wrapper" class = "hidden" >
< form id = "searchbar-outer" class = "searchbar-outer" >
< input type = "search" id = "searchbar" name = "searchbar" placeholder = "Search this book ..." aria-controls = "searchresults-outer" aria-describedby = "searchresults-header" >
< / form >
< div id = "searchresults-outer" class = "searchresults-outer hidden" >
< div id = "searchresults-header" class = "searchresults-header" > < / div >
< ul id = "searchresults" >
< / ul >
< / div >
< / div >
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
< script type = "text/javascript" >
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
< / script >
< div id = "content" class = "content" >
< main >
<!-- Page table of contents -->
< div class = "sidetoc" >
< nav class = "pagetoc" > < / nav >
< / div >
< h1 id = "user-directory-api-implementation" > < a class = "header" href = "#user-directory-api-implementation" > User Directory API Implementation< / a > < / h1 >
2023-09-26 13:45:43 +00:00
< p > The user directory is maintained based on users that are 'visible' to the homeserver -
i.e. ones which are local to the server and ones which any local user shares a
room with.< / p >
< p > The directory info is stored in various tables, which can sometimes get out of
sync (although this is considered a bug). If this happens, for now the
2021-11-19 19:40:11 +00:00
solution to fix it is to use the < a href = "usage/administration/admin_api/background_updates.html#run" > admin API< / a >
and execute the job < code > regenerate_directory< / code > . This should then start a background task to
2023-09-26 13:45:43 +00:00
flush the current tables and regenerate the directory. Depending on the size
of your homeserver (number of users and rooms) this can take a while.< / p >
2021-09-10 09:54:59 +00:00
< h2 id = "data-model" > < a class = "header" href = "#data-model" > Data model< / a > < / h2 >
< p > There are five relevant tables that collectively form the " user directory" .
2023-09-26 13:45:43 +00:00
Three of them track a list of all known users. The last two (collectively called
the " search tables" ) track which users are visible to each other.< / p >
2021-09-10 09:54:59 +00:00
< p > From all of these tables we exclude three types of local user:< / p >
< ul >
< li > support users< / li >
< li > appservice users< / li >
< li > deactivated users< / li >
< / ul >
2023-09-26 13:45:43 +00:00
< p > A description of each table follows:< / p >
2021-09-10 09:54:59 +00:00
< ul >
< li >
2023-09-26 13:45:43 +00:00
< p > < code > user_directory< / code > . This contains the user ID, display name and avatar of each user.< / p >
2021-09-10 09:54:59 +00:00
< ul >
2023-09-26 13:45:43 +00:00
< li > Because there is only one directory entry per user, it is important that it
only contain publicly visible information. Otherwise, this will leak the
2021-09-10 09:54:59 +00:00
nickname or avatar used in a private room.< / li >
< li > Indexed on rooms. Indexed on users.< / li >
< / ul >
< / li >
< li >
< p > < code > user_directory_search< / code > . To be joined to < code > user_directory< / code > . It contains an extra
2023-09-26 13:45:43 +00:00
column that enables full text search based on user IDs and display names.
Different schemas for SQLite and Postgres are used.< / p >
2021-09-10 09:54:59 +00:00
< ul >
< li > Indexed on the full text search data. Indexed on users.< / li >
< / ul >
< / li >
< li >
< p > < code > user_directory_stream_pos< / code > . When the initial background update to populate
the directory is complete, we record a stream position here. This indicates
that synapse should now listen for room changes and incrementally update
2023-09-26 13:45:43 +00:00
the directory where necessary. (See < a href = "development/synapse_architecture/streams.html" > stream positions< / a > .)< / p >
2021-09-10 09:54:59 +00:00
< / li >
< li >
2023-09-26 13:45:43 +00:00
< p > < code > users_in_public_rooms< / code > . Contains associations between users and the public
rooms they're in. Used to determine which users are in public rooms and should
be publicly visible in the directory. Both local and remote users are tracked.< / p >
2021-09-10 09:54:59 +00:00
< / li >
< li >
< p > < code > users_who_share_private_rooms< / code > . Rows are triples < code > (L, M, room id)< / code > where < code > L< / code >
is a local user and < code > M< / code > is a local or remote user. < code > L< / code > and < code > M< / code > should be
different, but this isn't enforced by a constraint.< / p >
2023-09-26 13:45:43 +00:00
< p > Note that if two local users share a room then there will be two entries:
< code > (user1, user2, !room_id)< / code > and < code > (user2, user1, !room_id)< / code > .< / p >
2021-09-10 09:54:59 +00:00
< / li >
< / ul >
2023-09-26 13:45:43 +00:00
< h2 id = "configuration-options" > < a class = "header" href = "#configuration-options" > Configuration options< / a > < / h2 >
< p > The exact way user search works can be tweaked via some server-level
< a href = "usage/configuration/config_documentation.html#user_directory" > configuration options< / a > .< / p >
< p > The information is not repeated here, but the options are mentioned below.< / p >
< h2 id = "search-algorithm" > < a class = "header" href = "#search-algorithm" > Search algorithm< / a > < / h2 >
< p > If < code > search_all_users< / code > is < code > false< / code > , then results are limited to users who:< / p >
< ol >
< li > Are found in the < code > users_in_public_rooms< / code > table, or< / li >
< li > Are found in the < code > users_who_share_private_rooms< / code > where < code > L< / code > is the requesting
user and < code > M< / code > is the search result.< / li >
< / ol >
< p > Otherwise, if < code > search_all_users< / code > is < code > true< / code > , no such limits are placed and all
users known to the server (matching the search query) will be returned.< / p >
< p > By default, locked users are not returned. If < code > show_locked_users< / code > is < code > true< / code > then
no filtering on the locked status of a user is done.< / p >
< p > The user provided search term is lowercased and normalized using < a href = "https://en.wikipedia.org/wiki/Unicode_equivalence#Normalization" > NFKC< / a > ,
this treats the string as case-insensitive, canonicalizes different forms of the
same text, and maps some " roughly equivalent" characters together.< / p >
< p > The search term is then split into words:< / p >
< ul >
< li > If < a href = "https://en.wikipedia.org/wiki/International_Components_for_Unicode" > ICU< / a > is
available, then the system's < a href = "https://unicode-org.github.io/icu/userguide/locale/#default-locales" > default locale< / a >
will be used to break the search term into words. (See the
< a href = "setup/installation.html" > installation instructions< / a > for how to install ICU.)< / li >
2023-10-02 15:06:43 +00:00
< li > If unavailable, then runs of ASCII characters, numbers, underscores, and hyphens
2023-09-26 13:45:43 +00:00
are considered words.< / li >
< / ul >
2024-04-26 18:12:17 +00:00
< p > The queries for PostgreSQL and SQLite are detailed below, but their overall goal
2023-09-26 13:45:43 +00:00
is to find matching users, preferring users who are " real" (e.g. not bots,
2024-04-26 18:12:17 +00:00
not deactivated). It is assumed that real users will have a display name and
2023-09-26 13:45:43 +00:00
avatar set.< / p >
< h3 id = "postgresql" > < a class = "header" href = "#postgresql" > PostgreSQL< / a > < / h3 >
< p > The above words are then transformed into two queries:< / p >
< ol >
< li > " exact" which matches the parsed words exactly (using < a href = "https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-PARSING-QUERIES" > < code > to_tsquery< / code > < / a > );< / li >
< li > " prefix" which matches the parsed words as prefixes (using < code > to_tsquery< / code > ).< / li >
< / ol >
< p > Results are composed of all rows in the < code > user_directory_search< / code > table whose information
matches one (or both) of these queries. Results are ordered by calculating a weighted
score for each result, higher scores are returned first:< / p >
< ul >
< li > 4x if a user ID exists.< / li >
< li > 1.2x if the user has a display name set.< / li >
< li > 1.2x if the user has an avatar set.< / li >
< li > 0x-3x by the full text search results using the < a href = "https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-RANKING" > < code > ts_rank_cd< / code > function< / a >
against the " exact" search query; this has four variables with the following weightings:
< ul >
< li > < code > D< / code > : 0.1 for the user ID's domain< / li >
< li > < code > C< / code > : 0.1 for unused< / li >
< li > < code > B< / code > : 0.9 for the user's display name (or an empty string if it is not set)< / li >
< li > < code > A< / code > : 0.1 for the user ID's localpart< / li >
< / ul >
< / li >
< li > 0x-1x by the full text search results using the < code > ts_rank_cd< / code > function against the
" prefix" search query. (Using the same weightings as above.)< / li >
< li > If < code > prefer_local_users< / code > is < code > true< / code > , then 2x if the user is local to the homeserver.< / li >
< / ul >
< p > Note that < code > ts_rank_cd< / code > returns a weight between 0 and 1. The initial weighting of
all results is 1.< / p >
< h3 id = "sqlite" > < a class = "header" href = "#sqlite" > SQLite< / a > < / h3 >
< p > Results are composed of all rows in the < code > user_directory_search< / code > whose information
matches the query. Results are ordered by the following information, with each
subsequent column used as a tiebreaker, for each result:< / p >
< ol >
< li > By the < a href = "https://www.sqlite.org/windowfunctions.html#built_in_window_functions" > < code > rank< / code > < / a >
of the full text search results using the < a href = "https://www.sqlite.org/fts3.html#matchinfo" > < code > matchinfo< / code > function< / a > . Higher
ranks are returned first.< / li >
< li > If < code > prefer_local_users< / code > is < code > true< / code > , then users local to the homeserver are
returned first.< / li >
< li > Users with a display name set are returned first.< / li >
< li > Users with an avatar set are returned first.< / li >
< / ol >
2021-06-03 16:21:02 +00:00
< / main >
< nav class = "nav-wrapper" aria-label = "Page navigation" >
<!-- Mobile navigation buttons -->
2022-07-12 19:02:38 +00:00
< a rel = "prev" href = "consent_tracking.html" class = "mobile-nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
2021-06-03 16:21:02 +00:00
< i class = "fa fa-angle-left" > < / i >
< / a >
< a rel = "next" href = "message_retention_policies.html" class = "mobile-nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
< i class = "fa fa-angle-right" > < / i >
< / a >
< div style = "clear: both" > < / div >
< / nav >
< / div >
< / div >
< nav class = "nav-wide-wrapper" aria-label = "Page navigation" >
2022-07-12 19:02:38 +00:00
< a rel = "prev" href = "consent_tracking.html" class = "nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
2021-06-03 16:21:02 +00:00
< i class = "fa fa-angle-left" > < / i >
< / a >
< a rel = "next" href = "message_retention_policies.html" class = "nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
< i class = "fa fa-angle-right" > < / i >
< / a >
< / nav >
< / div >
< script type = "text/javascript" >
window.playground_copyable = true;
< / script >
< script src = "elasticlunr.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "mark.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "searcher.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "clipboard.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "highlight.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "book.js" type = "text/javascript" charset = "utf-8" > < / script >
<!-- Custom JS scripts -->
< script type = "text/javascript" src = "docs/website_files/table-of-contents.js" > < / script >
2023-12-11 14:20:01 +00:00
< script type = "text/javascript" src = "docs/website_files/version-picker.js" > < / script >
< script type = "text/javascript" src = "docs/website_files/version.js" > < / script >
2021-06-03 16:21:02 +00:00
< / body >
2023-12-12 17:47:01 +00:00
< / html >
