networkid

Documentation

Overview

Package networkid contains string types used to represent different kinds of identifiers on remote networks.

Except for BridgeID, all types in this package are only generated by network connectors. Network connectors may generate and parse these types any way they want, all other components will treat them as opaque identifiers and will not parse them nor assume anything about them. However, identifiers are stored in the bridge database, so backwards-compatibility must be considered when changing the format.

All IDs are scoped to a bridge, i.e. they don't need to be unique across different bridges. However, most IDs need to be globally unique within the bridge, i.e. the same ID must refer to the same entity even from another user's point of view. If the remote network does not directly provide such globally unique identifiers, the network connector should prefix them with a user ID or other identifier to make them unique.

Index

• type AvatarID
• type BridgeID
• type EmojiID
• type MediaID
• type MessageID
• type MessageOptionalPartID
• type MessagePartID
• type PaginationCursor
• type PartID
• type PortalID
• type PortalKey
  • func (pk PortalKey) IsEmpty() bool
  • func (pk PortalKey) MarshalZerologObject(evt *zerolog.Event)
  • func (pk PortalKey) String() string
• type TransactionID
• type UserID
• type UserLoginID

Types

type AvatarID

type AvatarID string

AvatarID is the ID of a user or room avatar on the remote network.

It may be a real URL, an opaque identifier, or anything in between. It should be an identifier that can be acquired from the remote network without downloading the entire avatar.

In general, it is preferred to use a stable identifier which only changes when the avatar changes. However, the bridge will also hash the avatar data to check for changes before sending an avatar update to Matrix, so the avatar ID being slightly unstable won't be the end of the world.

type BridgeID

type BridgeID string

BridgeID is an opaque identifier for a bridge

type EmojiID

type EmojiID string

EmojiID is the ID of a reaction emoji on the remote network.

On networks that only allow one reaction per message, an empty string should be used to apply the unique constraints in the database appropriately. On networks that allow multiple emojis, this is the unicode emoji or a network-specific shortcode.

type MediaID

type MediaID []byte

MediaID represents a media identifier that can be downloaded from the remote network at any point in the future.

This is used to implement on-demand media downloads. The network connector can ask the Matrix connector to generate a content URI from a media ID. Then, when the Matrix connector wants to download the media, it will parse the content URI and ask the network connector for the data using the media ID.

type MessageID

type MessageID string

MessageID is the ID of a message on the remote network.

Message IDs must be unique across rooms and consistent across users (i.e. globally unique within the bridge).

type MessageOptionalPartID

type MessageOptionalPartID struct {
	MessageID MessageID
	PartID    *PartID
}

MessageOptionalPartID refers to a specific part of a message by combining a message ID and an optional part ID. If the part ID is not set, this should refer to the first part ID sorted alphabetically.

type MessagePartID

type MessagePartID struct {
	MessageID MessageID
	PartID    PartID
}

MessagePartID refers to a specific part of a message by combining a message ID and a part ID.

type PaginationCursor

type PaginationCursor string

PaginationCursor is a cursor used for paginating message history.

type PartID

type PartID string

PartID is the ID of a message part on the remote network (e.g. index of image in album).

Part IDs are only unique within a message, not globally. To refer to a specific message part globally, use the MessagePartID tuple struct.

type PortalID

type PortalID string

PortalID is the ID of a room on the remote network. A portal ID alone should identify group chats uniquely, and also DMs when scoped to a user login ID (see PortalKey).

type PortalKey

type PortalKey struct {
	ID       PortalID
	Receiver UserLoginID
}

PortalKey is the unique key of a room on the remote network. It combines a portal ID and a receiver ID.

The Receiver field is generally only used for DMs, and should be empty for group chats. The purpose is to segregate DMs by receiver, so that the same DM has separate rooms even if both sides are logged into the bridge. Also, for networks that use user IDs as DM chat IDs, the receiver is necessary to have separate rooms for separate users who have a DM with the same remote user.

It is also permitted to use a non-empty receiver for group chats if there is a good reason to segregate them. For example, Telegram's non-supergroups have user-scoped message IDs instead of chat-scoped IDs, which is easier to manage with segregated rooms.

As a special case, Receiver MUST be set if the Bridge.Config.SplitPortals flag is set to true. The flag is intended for puppeting-only bridges which want multiple logins to create separate portals for each user.

func (PortalKey) IsEmpty

func (pk PortalKey) IsEmpty() bool

func (PortalKey) MarshalZerologObject

func (pk PortalKey) MarshalZerologObject(evt *zerolog.Event)

func (PortalKey) String

func (pk PortalKey) String() string

type TransactionID

type TransactionID string

TransactionID is a client-generated identifier for a message send operation on the remote network.

Transaction IDs must be unique across users in a room, but don't need to be unique across different rooms.

type UserID

type UserID string

UserID is the ID of a user on the remote network.

User IDs must be globally unique within the bridge for identifying a specific remote user.

type UserLoginID

type UserLoginID string

UserLoginID is the ID of the user being controlled on the remote network.

It may be the same shape as UserID. However, being the same shape is not required, and the central bridge module and Matrix connectors will never assume it is. Instead, the bridge will use methods like maunium.net/go/mautrix/bridgev2.NetworkAPI.IsThisUser to check if a user ID is associated with a given UserLogin. The network connector is of course allowed to assume a UserLoginID is equivalent to a UserID, because it is the one defining both types.