Federation¶

Endpoints¶

Federation ¶

This API allows a server administrator to manage Synapse's federation with other homeservers.

Source code in matrix_admin_sdk/endpoints/v1/federation.py

class Federation(Endpoint):
    """
    This API allows a server administrator to manage Synapse's federation with
    other homeservers.
    """

    async def get_destinations(
        self,
        from_: int = 0,
        limit: int = 100,
        order_by: Optional[OrderBy] = None,
        dir_: str = "f",
    ) -> DestinationsModel:
        """
        This API gets the current destination retry timing info for all remote servers.

        The list contains all the servers with which the server federates,
        regardless of whether an error occurred or not. If an error occurs,
        it may take up to 20 minutes for the error to be displayed here, as
        a complete retry must have failed.
        Args:
            from_: Offset in the returned list. Defaults to 0
            limit: Maximum amount of destinations to return. Defaults to 100.
            order_by: The method in which to sort the returned list of destinations.
                Default: OrderBy.DESTINATION
            dir_: Direction of room order. Either f for forwards or b for
                backwards. Setting this value to b will reverse the above sort order.
                Defaults to f

        Returns:

        """
        url = self.url("federation/destinations")
        order_by = order_by if order_by is not None else OrderBy.DESTINATION
        params = {
            "from": from_,
            "limit": limit,
            "order_by": order_by.value,
            "dir": dir_,
        }
        result = await self.request(RequestMethods.GET, url, params=params)
        res: DestinationsModel = DestinationsModel.from_dict(result)
        return res

    async def get_destination_details(self, destination: str) -> DestinationModel:
        """
        This API gets the retry timing info for a specific remote server.
        Args:
            destination: Name of the remote server

        Returns: DestinationModel

        """
        url = self.url(f"federation/destinations/{destination}")
        result = await self.request(RequestMethods.GET, url)
        res: DestinationModel = DestinationModel.from_dict(result)
        return res

    async def get_destination_rooms(
        self,
        destination: str,
        from_: int = 0,
        limit: int = 100,
        dir_: str = "f",
    ) -> DestinationRoomsModel:
        """
        This API gets the rooms that federate with a specific remote server.

        Args:
            destination: Name of the remote server
            from_: Offset in the returned list. Defaults to 0
            limit: Maximum amount of destinations to return. Defaults to 100.
            dir_: Direction of room order by room_id. Either f for forwards
                or b for backwards. Defaults to f

        Returns: DestinationRoomsModel

        """
        url = self.url(f"federation/destinations/{destination}/rooms")
        params = {
            "from": from_,
            "limit": limit,
            "dir": dir_,
        }
        result = await self.request(RequestMethods.GET, url, params=params)
        res: DestinationRoomsModel = DestinationRoomsModel.from_dict(result)
        return res

    async def reset_connection_timeout(self, destination: str) -> None:
        """
        Synapse makes federation requests to other homeservers. If a federation
        request fails, Synapse will mark the destination homeserver as offline,
        preventing any future requests to that server for a "cooldown" period.
        This period grows over time if the server continues to fail its
        responses (exponential backoff).

        Admins can cancel the cooldown period with this API.

        This API resets the retry timing for a specific remote server and tries
        to connect to the remote server again. It does not wait for the next
        retry_interval. The connection must have previously run into an error
        and retry_last_ts (Destination Details API) must not be equal to 0.

        The connection attempt is carried out in the background and can take
        a while even if the API already returns the http status 200.
        Args:
            destination: Name of the remote server

        Returns: None

        """
        url = self.url(f"federation/destinations/{destination}/reset_connection")
        await self.request(RequestMethods.POST, url, json={})

`get_destination_details(self, destination)` `async` ¶

This API gets the retry timing info for a specific remote server.

Parameters:

Name	Type	Description	Default
`destination`	`str`	Name of the remote server	required

Source code in matrix_admin_sdk/endpoints/v1/federation.py

async def get_destination_details(self, destination: str) -> DestinationModel:
    """
    This API gets the retry timing info for a specific remote server.
    Args:
        destination: Name of the remote server

    Returns: DestinationModel

    """
    url = self.url(f"federation/destinations/{destination}")
    result = await self.request(RequestMethods.GET, url)
    res: DestinationModel = DestinationModel.from_dict(result)
    return res

`get_destination_rooms(self, destination, from_=0, limit=100, dir_='f')` `async` ¶

This API gets the rooms that federate with a specific remote server.

Parameters:

Name	Type	Description	Default
`destination`	`str`	Name of the remote server	required
`from_`	`int`	Offset in the returned list. Defaults to 0	`0`
`limit`	`int`	Maximum amount of destinations to return. Defaults to 100.	`100`
`dir_`	`str`	Direction of room order by room_id. Either f for forwards or b for backwards. Defaults to f	`'f'`

Source code in matrix_admin_sdk/endpoints/v1/federation.py

async def get_destination_rooms(
    self,
    destination: str,
    from_: int = 0,
    limit: int = 100,
    dir_: str = "f",
) -> DestinationRoomsModel:
    """
    This API gets the rooms that federate with a specific remote server.

    Args:
        destination: Name of the remote server
        from_: Offset in the returned list. Defaults to 0
        limit: Maximum amount of destinations to return. Defaults to 100.
        dir_: Direction of room order by room_id. Either f for forwards
            or b for backwards. Defaults to f

    Returns: DestinationRoomsModel

    """
    url = self.url(f"federation/destinations/{destination}/rooms")
    params = {
        "from": from_,
        "limit": limit,
        "dir": dir_,
    }
    result = await self.request(RequestMethods.GET, url, params=params)
    res: DestinationRoomsModel = DestinationRoomsModel.from_dict(result)
    return res

`get_destinations(self, from_=0, limit=100, order_by=None, dir_='f')` `async` ¶

This API gets the current destination retry timing info for all remote servers.

The list contains all the servers with which the server federates, regardless of whether an error occurred or not. If an error occurs, it may take up to 20 minutes for the error to be displayed here, as a complete retry must have failed.

Parameters:

Name	Type	Description	Default
`from_`	`int`	Offset in the returned list. Defaults to 0	`0`
`limit`	`int`	Maximum amount of destinations to return. Defaults to 100.	`100`
`order_by`	`Optional[matrix_admin_sdk.endpoints.v1.federation.OrderBy]`	The method in which to sort the returned list of destinations. Default: OrderBy.DESTINATION	`None`
`dir_`	`str`	Direction of room order. Either f for forwards or b for backwards. Setting this value to b will reverse the above sort order. Defaults to f	`'f'`

Source code in matrix_admin_sdk/endpoints/v1/federation.py

async def get_destinations(
    self,
    from_: int = 0,
    limit: int = 100,
    order_by: Optional[OrderBy] = None,
    dir_: str = "f",
) -> DestinationsModel:
    """
    This API gets the current destination retry timing info for all remote servers.

    The list contains all the servers with which the server federates,
    regardless of whether an error occurred or not. If an error occurs,
    it may take up to 20 minutes for the error to be displayed here, as
    a complete retry must have failed.
    Args:
        from_: Offset in the returned list. Defaults to 0
        limit: Maximum amount of destinations to return. Defaults to 100.
        order_by: The method in which to sort the returned list of destinations.
            Default: OrderBy.DESTINATION
        dir_: Direction of room order. Either f for forwards or b for
            backwards. Setting this value to b will reverse the above sort order.
            Defaults to f

    Returns:

    """
    url = self.url("federation/destinations")
    order_by = order_by if order_by is not None else OrderBy.DESTINATION
    params = {
        "from": from_,
        "limit": limit,
        "order_by": order_by.value,
        "dir": dir_,
    }
    result = await self.request(RequestMethods.GET, url, params=params)
    res: DestinationsModel = DestinationsModel.from_dict(result)
    return res

`reset_connection_timeout(self, destination)` `async` ¶

Synapse makes federation requests to other homeservers. If a federation request fails, Synapse will mark the destination homeserver as offline, preventing any future requests to that server for a "cooldown" period. This period grows over time if the server continues to fail its responses (exponential backoff).

Admins can cancel the cooldown period with this API.

This API resets the retry timing for a specific remote server and tries to connect to the remote server again. It does not wait for the next retry_interval. The connection must have previously run into an error and retry_last_ts (Destination Details API) must not be equal to 0.

The connection attempt is carried out in the background and can take a while even if the API already returns the http status 200.

Parameters:

Name	Type	Description	Default
`destination`	`str`	Name of the remote server	required

Source code in matrix_admin_sdk/endpoints/v1/federation.py

async def reset_connection_timeout(self, destination: str) -> None:
    """
    Synapse makes federation requests to other homeservers. If a federation
    request fails, Synapse will mark the destination homeserver as offline,
    preventing any future requests to that server for a "cooldown" period.
    This period grows over time if the server continues to fail its
    responses (exponential backoff).

    Admins can cancel the cooldown period with this API.

    This API resets the retry timing for a specific remote server and tries
    to connect to the remote server again. It does not wait for the next
    retry_interval. The connection must have previously run into an error
    and retry_last_ts (Destination Details API) must not be equal to 0.

    The connection attempt is carried out in the background and can take
    a while even if the API already returns the http status 200.
    Args:
        destination: Name of the remote server

    Returns: None

    """
    url = self.url(f"federation/destinations/{destination}/reset_connection")
    await self.request(RequestMethods.POST, url, json={})

Models¶

DestinationsModel¶

A list of destinations.

Attributes:

Name	Type	Description
`destinations`	`list[DestinationModel]`	An array of objects, each containing information about a destination
`total`	`int`	Total number of destinations
`next_token`	`int\|None`	Indication for pagination

Source code in matrix_admin_sdk/models/v1/federation.py

class DestinationsModel(BaseModel):
    """
    A list of destinations.
    Attributes:
        destinations (list[DestinationModel]): An array of objects, each containing
            information about a destination
        total (int): Total number of destinations
        next_token (int|None): Indication for pagination
    """

    destinations: List[DestinationModel]
    total: int
    next_token: Optional[int] = None

    @classmethod
    def from_dict(cls, data: Dict[str, Any]) -> "DestinationsModel":
        destinations = [DestinationModel.from_dict(d) for d in data["destinations"]]
        return cls(
            destinations=destinations,
            total=data["total"],
            next_token=data.get("next_token"),
        )

DestinationModel¶

Class representing a destination model.

Attributes:

Name	Type	Description
`destination`	`str`	Name of the remote server to federate
`retry_last_ts`	`int`	The last time Synapse tried and failed to reach the remote server, in ms. This is 0 if the last attempt to communicate with the remote server was successful
`retry_interval`	`int`	How long since the last time Synapse tried to reach the remote server before trying again, in ms. This is 0 if no further retrying occuring
`failure_ts`	`Optional[int]`	(int\|None): The first time Synapse tried and failed to reach the remote server, in ms. This is null if communication with the remote server has never failed.
`last_successful_stream_ordering`	`Optional[int]`	(int\|None): The stream ordering of the most recent successfully-sent PDU to this destination, or null if this information has not been tracked yet.

Source code in matrix_admin_sdk/models/v1/federation.py

class DestinationModel(BaseModel):
    """
    Class representing a destination model.
    Attributes:
        destination (str): Name of the remote server to federate
        retry_last_ts (int): The last time Synapse tried and failed to reach the
            remote server, in ms. This is 0 if the last attempt to communicate
            with the remote server was successful
        retry_interval (int): How long since the last time Synapse tried to reach
            the remote server before trying again, in ms. This is 0
            if no further retrying occuring
        failure_ts: (int|None): The first time Synapse tried and failed to reach
            the remote server, in ms. This is null if communication with the
            remote server has never failed.
        last_successful_stream_ordering: (int|None): The stream ordering of the
            most recent successfully-sent PDU to this destination, or null if this
            information has not been tracked yet.
    """

    destination: str
    retry_last_ts: int
    retry_interval: int
    failure_ts: Optional[int] = None
    last_successful_stream_ordering: Optional[int] = None

DestinationRoomsModel¶

A list of rooms in a destination.

Attributes:

Name	Type	Description
`rooms`	`list[DestinationRoomModel]`	An array of objects, each containing information about a room
`total`	`int`	Total number of destinations
`next_token`	`int\|None`	Indication for pagination

Source code in matrix_admin_sdk/models/v1/federation.py

class DestinationRoomsModel(BaseModel):
    """
    A list of rooms in a destination.
    Attributes:
        rooms (list[DestinationRoomModel]): An array of objects, each containing
            information about a room
        total (int): Total number of destinations
        next_token (int|None): Indication for pagination
    """

    rooms: List[DestinationRoomModel]
    total: int
    next_token: Optional[int] = None

    @classmethod
    def from_dict(cls, data: Dict[str, Any]) -> "DestinationRoomsModel":
        rooms = [DestinationRoomModel.from_dict(d) for d in data["rooms"]]
        return cls(
            rooms=rooms,
            total=data["total"],
            next_token=data.get("next_token"),
        )

DestinationRoomModel¶

Class representing a destination room model.

Attributes:

Name	Type	Description
`room_id`	`str`	The ID of the room
`stream_ordering`	`int`	The stream ordering of the most recent successfully-sent PDU to this destination in this room

Source code in matrix_admin_sdk/models/v1/federation.py

class DestinationRoomModel(BaseModel):
    """
    Class representing a destination room model.
    Attributes:
        room_id (str): The ID of the room
        stream_ordering (int): The stream ordering of the most recent
            successfully-sent PDU to this destination in this room
    """

    room_id: str
    stream_ordering: int

Federation¶

Endpoints¶

Federation¶

get_destination_details(self, destination) async ¶

get_destination_rooms(self, destination, from_=0, limit=100, dir_='f') async ¶

get_destinations(self, from_=0, limit=100, order_by=None, dir_='f') async ¶

reset_connection_timeout(self, destination) async ¶

Models¶

DestinationsModel¶

DestinationModel¶

DestinationRoomsModel¶

DestinationRoomModel¶

Federation ¶

`get_destination_details(self, destination)` `async` ¶

`get_destination_rooms(self, destination, from_=0, limit=100, dir_='f')` `async` ¶

`get_destinations(self, from_=0, limit=100, order_by=None, dir_='f')` `async` ¶

`reset_connection_timeout(self, destination)` `async` ¶