Synadm Package
The synadm
package contains the synadm.api
module which is
responsible for accessing the Synapse admin API endpoints and the regular Matrix
API endpoints. Also some helper methods, e.g to calculate time-related things
are to be found in this module:
Synapse admin API and regular Matrix API clients
Most API calls defined in this module respect the API’s defaults and only pass what’s necessary in the request body.
A fully qualified Matrix user ID looks like this: @user:server, where server often is a domain name only, e.g @user@example.org
See https://github.com/matrix-org/synapse/tree/master/docs/admin_api for documentation of the Synapse admin APIs and the Matrix spec at https://matrix.org/docs/spec/#matrix-apis.
- class synadm.api.ApiRequest(log, user, token, base_url, path, timeout, debug)
Bases:
object
Basic API request handling and helper utilities
This is subclassed by SynapseAdmin and Matrix
- query(method, urlpart, params=None, data=None, token=None, base_url_override=None, verify=True)
Generic wrapper around requests methods.
Handles requests methods, logging and exceptions.
- Parameters
urlpart (string) – The path to the API endpoint, excluding self.base_url and self.path (the part after proto://fqdn:port/path).
params (dict, optional) – URL parameters (?param1&paarm2). Defaults to None.
data (dict, optional) – Request body used in POST, PUT, DELETE requests. Defaults to None.
base_url_override (bool) – The default setting of self.base_url set on initialization can be overwritten using this argument.
verify (bool) – Mandatory SSL verification is turned on by default and can be turned off using this method.
- Returns
- Usually a JSON string containing
the response of the API; responses that are not 200(OK) (usally error messages returned by the API) will also be returned as JSON strings. On exceptions the error type and description are logged and None is returned.
- Return type
string or None
- _timestamp_from_days_ago(days)
Get a unix timestamp in ms from days ago
- Parameters
days (int) – number of days
- Returns
a unix timestamp in milliseconds (ms)
- Return type
int
- _timestamp_from_days_ahead(days)
Get a unix timestamp in ms for the given number of days ahead
- Parameters
days (int) – number of days
- Returns
a unix timestamp in milliseconds (ms)
- Return type
int
- _timestamp_from_datetime(_datetime)
Get a unix timestamp in ms from a datetime object
- Parameters
_datetime (datetime object) – an object built by datetime.datetime
- Returns
a unix timestamp in milliseconds (ms)
- Return type
int
- _datetime_from_timestamp(timestamp, as_str=False)
Get a datetime object from a unix timestamp in ms
- Parameters
timestamp (int) – a unix timestamp in milliseconds (ms)
- Returns
- an object built by datetime.datetime.
If as_str is set, return a string formatted by self._format_datetime() instead.
- Return type
datetime object
- _format_datetime(datetime_obj)
Get a formatted date as a string.
- Parameters
datetime_obj (int) – A datetime object.
- Returns
- A date in the format we use it throughout synadm. No sanity
checking.
- Return type
string
- class synadm.api.MiscRequest(log, timeout, debug)
Bases:
ApiRequest
Miscellaneous HTTP requests
- Inheritance:
- ApiRequest (object): parent class containing general properties and
methods for requesting REST API’s
- federation_uri_well_known(base_url)
Retrieve the URI to the Server-Server (Federation) API port via the .well-known resource of a Matrix server/domain.
- Parameters
base_url – proto://name or proto://fqdn
- Returns
- https://fqdn:port of the delegated server for Server-Server
communication between Matrix homeservers or None on errors.
- Return type
string
- class synadm.api.Matrix(log, user, token, base_url, matrix_path, timeout, debug)
Bases:
ApiRequest
Matrix API client
- Inheritance:
- ApiRequest (object): parent class containing general properties and
methods for requesting REST API’s
- user_login(user_id, password)
Login as a Matrix user and retrieve an access token
- Parameters
user_id (string) – a fully qualified Matrix user ID
password (string) – the Matrix user’s password
- Returns
- JSON string containing a token suitable to access the
Matrix API on the user’s behalf, a device_id and some more details on Matrix server and user.
- Return type
string
- room_get_id(room_alias)
Get the room ID for a given room alias
- Parameters
room_alias (string) – A Matrix room alias (#name:example.org)
- Returns
- A dict containing the room ID for the alias.
If room_id is missing in the response we return the whole response as it might contain Synapse’s error message.
- Return type
string, dict or None
- room_get_aliases(room_id)
Get a list of room aliases for a given room ID
- Parameters
room_id (string) – A Matrix room ID (!abc123:example.org)
- Returns
- A dict containing a list of room aliases, Synapse’s
error message or None on exceptions.
- Return type
dict or None
- raw_request(endpoint, method, data, token=None)
- server_name_keys_api(server_server_uri)
Retrieve the Matrix server’s own homeserver name via the Server-Server (Federation) API.
- Parameters
server_server_uri (string) – proto://name:port or proto://fqdn:port
- Returns
The Matrix server’s homeserver name or FQDN, usually something like matrix.DOMAIN or DOMAIN
- Return type
string
- class synadm.api.SynapseAdmin(log, user, token, base_url, admin_path, timeout, debug)
Bases:
ApiRequest
Synapse admin API client
- Inheritance:
- ApiRequest (object): parent class containing general properties and
methods for requesting REST API’s
- user_list(_from, _limit, _guests, _deactivated, _name, _user_id)
List and search users
- Parameters
_from (int) – offsets user list by this number, used for pagination
_limit (int) – maximum number of users returned, used for pagination
_guests (bool) – enable/disable fetching of guest users
_deactivated (bool) – enable/disable fetching of deactivated users
_name (string) – user name localpart to search for, see Synapse admin API docs for details
_user_id (string) – fully qualified Matrix user ID to search for
- Returns
JSON string containing the found users
- Return type
string
- user_membership(user_id, return_aliases, matrix_api)
Get a list of rooms the given user is member of
- Parameters
user_id (string) – Fully qualified Matrix user ID
room_aliases (bool) – Return human readable room aliases instead of room ID’s if applicable.
matrix_api (object) – An initialized Matrix object needs to be passes as we need some Matrix API functionality here.
- Returns
- JSON string containing the admin API’s response or None if
an exception occured. See Synapse admin API docs for details.
- Return type
string
- user_deactivate(user_id, gdpr_erase)
Delete a given user
- Parameters
user_id (string) – fully qualified Matrix user ID
gdpr_erase (bool) – enable/disable gdpr-erasing the user, see Synapse admin API docs for details.
- Returns
- JSON string containing the admin API’s response or None if
an exception occured. See Synapse admin API docs for details.
- Return type
string
- user_password(user_id, password, no_logout)
Set the user password, and log the user out if requested
- Parameters
user_id (string) – fully qualified Matrix user ID
password (string) – new password that should be set
no_logout (bool) – the API defaults to logging out the user after password reset via the admin API, this option can be used to disable this behaviour.
- Returns
JSON string containing the admin API’s response or None if an exception occured. See Synapse admin API docs for details.
- Return type
string
- user_details(user_id)
Get information about a given user
Note that the admin API docs describe this function as “Query User Account”.
- Parameters
user_id (string) – fully qualified Matrix user ID
- Returns
- JSON string containing the admin API’s response or None if
an exception occured. See Synapse admin API docs for details.
- Return type
string
- user_login(user_id, expire_days, expire, _expire_ts)
Get an access token that can be used to authenticate as that user.
If one of the args expire_days, expire or _expire_ts is set, the valid_until_ms field will be sent to the API endpoint. If this is not the case the default of the API would be used. At the time of writing, this would be that tokens never expire.
Note: If this method is called by the CLI frontend code (synadm.cli.user.user_login_cmd), a default expiry date of 1 day (24h) is passed.
- Parameters
user_id (string) – fully qualified Matrix user ID
expire_days (int) – token should expire after this number of days
expire (datetime) – token should expire after this date/time - a datetime object (e.g. as generated by Click.DateTime())
_expire_ts (int) – token should expire after this date/time - a unix timestamp in ms.
- Returns
JSON string containing the admin API’s response or None if an exception occured. See Synapse admin API docs for details.
- Return type
string
- user_modify(user_id, password, display_name, threepid, avatar_url, admin, deactivation)
Create or update information about a given user
Threepid should be passed as a tuple in a tuple
- user_whois(user_id)
Return information about the active sessions for a specific user
- user_devices(user_id)
Return information about all devices for a specific user.
- Parameters
user_id (string) – Fully qualified Matrix user ID.
- Returns
- JSON string containing the admin API’s response or None if
an exception occured. See Synapse admin API docs for details.
- Return type
string
- user_devices_get_todelete(devices_data, min_days, min_surviving, device_id, readable_seen)
Gather a list of devices that possibly could be deleted.
This method is used by the ‘user prune-devices’ command.
- Parameters
devices_data (list) – Containing dicts of all the user’s devices, as returned by the user_devices method (the user/devices API endpoint).
min_days (int) – At least this number of days need to have passed from the last time a device was seen for it to be deleted. A reasonable default should be sent by the CLI level method.
min_surviving – At least this amount of devices will be kept alive. A reasonable default should be sent by the CLI level method.
device_id – Only search devices with this ID.
datetime – When True, ‘last seen timestamp’ is replaced with a human readable format.
- Returns
- Containing dicts of devices that possibly could be deleted.
If non apply, an empty list is returned.
- Return type
list
- user_devices_delete(user_id, devices)
Delete the specified devices for a specific user. Returns an empty JSON dict.
devices is a list of device IDs
- room_join(room_id_or_alias, user_id)
Allow an administrator to join an user account with a given user_id to a room with a given room_id_or_alias
- room_list(_from, limit, name, order_by, reverse)
List and search rooms
- room_details(room_id)
Get details about a room
- room_members(room_id)
Get a list of room members
- room_state(room_id)
Get a list of all state events in a room.
- Parameters
room_id (string) –
- Returns
- JSON string containing the admin API’s response or None if
an exception occured. See Synapse admin API docs for details.
- Return type
string
- room_power_levels(from_, limit, name, order_by, reverse, room_id=None, all_details=True, output_format='json')
Get a list of configured power_levels in all rooms.
or a single room.
- Parameters
room_id (string) – If left out, all rooms are fetched.
- Returns
- JSON string containing the admin API’s response or None if
an exception occured. See Synapse admin API docs for details.
- Return type
string
- room_delete(room_id, new_room_user_id, room_name, message, block, no_purge)
Delete a room and purge it if requested
- room_make_admin(room_id, user_id)
Grant a user room admin permission. If the user is not in the room, and it is not publicly joinable, then invite the user.
- room_media_list(room_id)
Get a list of known media in an (unencrypted) room.
- media_quarantine(server_name, media_id)
Quarantine a single piece of local or remote media
- room_media_quarantine(room_id)
Quarantine all local and remote media in a room
- user_media_quarantine(user_id)
Quarantine all local and remote media of a user
- user_media(user_id, _from, limit, order_by, reverse, readable)
Get a user’s uploaded media
- media_delete(server_name, media_id)
Delete a specific (local) media_id
- media_delete_by_date_or_size(server_name, before_days, before, _before_ts, _size_gt, delete_profiles)
Delete local media by date and/or size FIXME and/or?
- media_protect(media_id)
Protect a single piece of local or remote media
from being quarantined
- purge_media_cache(before_days, before, _before_ts)
Purge old cached remote media
- version()
Get the server version
- group_delete(group_id)
Delete a local group (community)
- purge_history(room_id, before_event_id, before_days, before, _before_ts, delete_local)
Purge room history
- purge_history_status(purge_id)
Get status of a recent history purge
The status will be one of active, complete, or failed.
- regtok_list(valid, readable_expiry)
List registration tokens
- Parameters
valid (bool) – List only valid (if True) or invalid (if False) tokens. Default is to list all tokens regardless of validity.
readable_expiry (bool) – If True, replace the expiry_time field with a human readable datetime. If False, expiry_time will be a unix timestamp.
- Returns
- JSON string containing the admin API’s response or None if
an exception occured. See Synapse admin API docs for details.
- Return type
string
- regtok_details(token, readable_expiry)
Get details about the given registration token
- Parameters
token (string) – The registration token in question
readable_expiry (bool) – If True, replace the expiry_time field with a human readable datetime. If False, expiry_time will be a unix timestamp.
- Returns
- JSON string containing the admin API’s response or None if
an exception occured. See Synapse admin API docs for details.
- Return type
string
- regtok_new(token, length, uses_allowed, expiry_ts, expire_at)
Create a new registration token
- Parameters
token (string) – Registration token to create. Default is randomly generated by the server.
length (int) – The length of the token to generate if the token is not provided.
uses_allowed (int) – The number of times the token can be used to complete a registration before it becomes invalid.
expiry_ts (int) – The latest time the registration token is valid. Given as the number of milliseconds since 1970-01-01 00:00:00 UTC.
expire_at (click.DateTime) – The latest time the registration token is valid.
- Returns
- JSON string containing the admin API’s response or None if
an exception occured. See Synapse admin API docs for details.
- Return type
string
- regtok_update(token, uses_allowed, expiry_ts, expire_at)
Update a registration token
- Parameters
token (string) – Registration token to update.
uses_allowed (int) – The number of times the token can be used to complete a registration before it becomes invalid.
expiry_ts (int) – The latest time the registration token is valid. Given as the number of milliseconds since 1970-01-01 00:00:00 UTC. -1 indicates no expiry.
expire_at (click.DateTime) – The latest time the registration token is valid.
- Returns
- JSON string containing the admin API’s response or None if
an exception occured. See Synapse admin API docs for details.
- Return type
string
- regtok_delete(token)
Delete a registration token
- Parameters
token (string) – The registration token to delete
- Returns
- JSON string containing the admin API’s response or None if
an exception occured. See Synapse admin API docs for details.
- Return type
string
- user_shadow_ban(user_id, unban)
Shadow-ban or unban a user.
- Parameters
user_id (string) – The user to be banned/unbanned.
unban (boolean) – Unban the specified user.
- notice_send(receivers, content_plain, content_html, paginate, regex)
Send server notices.
- Parameters
receivers (string) – Target(s) of the notice. Either localpart or regular expression matching localparts.
content_plain (string) – Unformatted text of the notice.
content_html (string) – HTML-formatted text of the notice.
paginate (int) – Limits to how many users the notice is sent at once. Users are fetched with the user_list method and using its pagination capabilities.
to_regex (bool) – Selects whether receivers should be interpreted as a regular expression or a single recipient.
- Returns
- A list of dictionaries, each containing the response of
what a single notice admin API call returned. Usually that is an event ID or an error. See Synapse admin API docs for details.
- Return type
list