slidgnal.gateway

Module Contents

Classes

Link	Abstract base class to implement gateway commands (chatbot and ad-hoc)
LinkedDevices	Abstract base class to implement gateway commands (chatbot and ad-hoc)
UnlinkDevice	Abstract base class to implement gateway commands (chatbot and ad-hoc)
LinkDevice	Abstract base class to implement gateway commands (chatbot and ad-hoc)
ChangeContactName	Abstract base class to implement gateway commands (chatbot and ad-hoc)
DeleteAccount	Abstract base class to implement gateway commands (chatbot and ad-hoc)
Gateway	The gateway component, handling registrations and un-registrations.
Signal	Extends SignaldAPI with handlers for events we are interested in.

Functions

fmt_time(t)

Attributes

log

class slidgnal.gateway.Link(xmpp)

Bases: slidge.command.Command

Abstract base class to implement gateway commands (chatbot and ad-hoc)

Parameters:

xmpp (slidge.core.gateway.BaseGateway) –

NAME = 'Link your signal account to slidge'

HELP = "Use an existing signal account with slidge as a 'secondary device'. You will need to keep your..."

ACCESS

PROPER_RECEIPTS = True

xmpp: Gateway

async run(_session, ifrom, *args)

Entry point of the command

Parameters:

• session – If triggered by a registered user, its slidge Session

• ifrom (slixmpp.JID) – JID of the command-triggering entity

• args – When triggered via chatbot type message, additional words after the CHAT_COMMAND string was passed

Returns:

Either a TableResult, a Form, a Confirmation, a text, or None

async show_code(form_values, _session, ifrom)

Parameters:

form_values (dict) –

async finish(_form_values, _session, ifrom, session_id, phone, device)

class slidgnal.gateway.LinkedDevices(xmpp)

Bases: slidge.command.Command

Abstract base class to implement gateway commands (chatbot and ad-hoc)

Parameters:

xmpp (slidge.core.gateway.BaseGateway) –

NAME = 'List the devices linked to your signal account'

HELP = 'List all the devices that have access to your signal account'

ACCESS

xmpp: Gateway

async run(session, ifrom, *args)

Entry point of the command

Parameters:

• session – If triggered by a registered user, its slidge Session

• ifrom (slixmpp.JID) – JID of the command-triggering entity

• args – When triggered via chatbot type message, additional words after the CHAT_COMMAND string was passed

Returns:

Either a TableResult, a Form, a Confirmation, a text, or None

class slidgnal.gateway.UnlinkDevice(xmpp)

Bases: slidge.command.Command

Abstract base class to implement gateway commands (chatbot and ad-hoc)

Parameters:

xmpp (slidge.core.gateway.BaseGateway) –

NAME = 'Remove a linked device'

HELP = 'Remove a device from you signal account'

ACCESS

xmpp: Gateway

async run(session, ifrom, *args)

Entry point of the command

Parameters:

• session – If triggered by a registered user, its slidge Session

• ifrom (slixmpp.JID) – JID of the command-triggering entity

• args – When triggered via chatbot type message, additional words after the CHAT_COMMAND string was passed

Returns:

Either a TableResult, a Form, a Confirmation, a text, or None

async finish(form_values, session, _jid)

Parameters:

• form_values (dict) –

• session (slidgnal.session.Session) –

class slidgnal.gateway.LinkDevice(xmpp)

Bases: slidge.command.Command

Abstract base class to implement gateway commands (chatbot and ad-hoc)

Parameters:

xmpp (slidge.core.gateway.BaseGateway) –

NAME = 'Link a new device to your signal account'

HELP = 'Use slidge to add a device to your signal account'

ACCESS

xmpp: Gateway

async run(session, ifrom, *args)

Entry point of the command

Parameters:

• session – If triggered by a registered user, its slidge Session

• ifrom (slixmpp.JID) – JID of the command-triggering entity

• args – When triggered via chatbot type message, additional words after the CHAT_COMMAND string was passed

Returns:

Either a TableResult, a Form, a Confirmation, a text, or None

async finish(form_values, session, _ifrom)

Parameters:

session (slidgnal.session.Session) –

class slidgnal.gateway.ChangeContactName(xmpp)

Bases: slidge.command.Command

Abstract base class to implement gateway commands (chatbot and ad-hoc)

Parameters:

xmpp (slidge.core.gateway.BaseGateway) –

NAME = 'Rename a signal contact'

HELP = 'Change the contact_name of a signal contact. This is stored on your signal account only.'

ACCESS

xmpp: Gateway

async run(session, ifrom, *args)

Entry point of the command

Parameters:

• session – If triggered by a registered user, its slidge Session

• ifrom (slixmpp.JID) – JID of the command-triggering entity

• args – When triggered via chatbot type message, additional words after the CHAT_COMMAND string was passed

Returns:

Either a TableResult, a Form, a Confirmation, a text, or None

async finish(form_values, session, _ifrom)

Parameters:

session (slidgnal.session.Session) –

class slidgnal.gateway.DeleteAccount(xmpp)

Bases: slidge.command.Command

Abstract base class to implement gateway commands (chatbot and ad-hoc)

Parameters:

xmpp (slidge.core.gateway.BaseGateway) –

NAME = 'Delete an account from signald'

HELP = 'This should only be done if there is a inconsistency between signald accounts slidge knows about...'

ACCESS

xmpp: Gateway

async run(_session, ifrom, *args)

Entry point of the command

Parameters:

• session – If triggered by a registered user, its slidge Session

• ifrom (slixmpp.JID) – JID of the command-triggering entity

• args – When triggered via chatbot type message, additional words after the CHAT_COMMAND string was passed

Returns:

Either a TableResult, a Form, a Confirmation, a text, or None

async finish(form_values, _session, _ifrom)

Parameters:

_session (slidgnal.session.Session) –

class slidgnal.gateway.Gateway

Bases: slidge.BaseGateway

The gateway component, handling registrations and un-registrations.

On slidge launch, a singleton is instantiated, and it will be made available to public classes such LegacyContact or BaseSession as the .xmpp attribute.

Must be subclassed by a legacy module to set up various aspects of the XMPP component behaviour, such as its display name or welcome message, via class attributes COMPONENT_NAME WELCOME_MESSAGE.

Abstract methods related to the registration process must be overriden for a functional Legacy Module:

• validate()

• validate_two_factor_code()

• get_qr_text()

• confirm_qr()

NB: Not all of these must be overridden, it depends on the REGISTRATION_TYPE.

The other methods, such as send_text() or react() are the same as those of LegacyContact and LegacyParticipant, because the component itself is also a “messaging actor”, ie, an XMPP Entity. For these methods, you need to specify the JID of the recipient with the mto parameter.

Since it inherits from slixmpp.componentxmpp.ComponentXMPP,you also have a hand on low-level XMPP interactions via slixmpp methods, e.g.:

self.send_presence(
    pfrom="somebody@component.example.com",
    pto="someonwelse@anotherexample.com",
)

However, you should not need to do so often since the classes of the plugin API provides higher level abstractions around most commonly needed use-cases, such as sending messages, or displaying a custom status.

COMPONENT_NAME = 'Signal (slidge)'

COMPONENT_TYPE = 'signal'

COMPONENT_AVATAR = 'https://upload.wikimedia.org/wikipedia/commons/5/56/Logo_Signal..png'

REGISTRATION_INSTRUCTIONS

REGISTRATION_FIELDS

REGISTRATION_TYPE

ROSTER_GROUP = 'Signal'

SEARCH_FIELDS

signal: asyncio.Future[Signal]

sessions_by_phone: dict[str, slidgnal.session.Session]

GROUPS = True

async connect_signal(socket)

Establish connection to the signald socker

Parameters:

socket (pathlib.Path) –

async validate(user_jid, registration_form)

Validate a user’s initial registration form.

Should raise the appropriate slixmpp.exceptions.XMPPError if the registration does not allow to continue the registration process.

If REGISTRATION_TYPE is a RegistrationType.SINGLE_STEP_FORM, this method should raise something if it wasn’t possible to successfully log in to the legacy service with the registration form content.

It is also used for other types of REGISTRATION_TYPE too, since the first step is always a form. If REGISTRATION_FIELDS is an empty list (ie, it declares no FormField), the “form” is effectively a confirmation dialog displaying REGISTRATION_INSTRUCTIONS.

Parameters:

• user_jid (slixmpp.JID) – JID of the user that has just registered

• registration_form (dict[str, Optional[str]]) – A dict where keys are the FormField.var attributes of the BaseGateway.REGISTRATION_FIELDS iterable

async validate_two_factor_code(user, code)

Called when the user enters their 2FA code.

Should raise the appropriate slixmpp.exceptions.XMPPError if the login fails, and return successfully otherwise.

Only used when REGISTRATION_TYPE is RegistrationType.TWO_FACTOR_CODE.

Parameters:

• user (slidge.GatewayUser) – The GatewayUser whose registration is pending Use their GatewayUser.bare_jid and/or registration_form attributes to get what you need.

• code (str) – The code they entered, either via “chatbot” message or adhoc command

async unregister(user)

Optionally override this if you need to clean additional stuff after a user has been removed from the permanent user_store.

By default, this just calls BaseSession.logout().

Parameters:

user (slidge.GatewayUser) –

class slidgnal.gateway.Signal(xmpp)

Bases: aiosignald.SignaldAPI

Extends SignaldAPI with handlers for events we are interested in.

Parameters:

• on_con_lost – its result will be set to True once the connection is lost If not given, will be automatically generated.

• xmpp (Gateway) –

async handle_WebSocketConnectionState(state, payload)

We should not care much about this since

Parameters:

• state (aiosignald.generated.WebSocketConnectionStatev1) –

• payload –

async handle_ListenerState(state, payload)

Deprecated in signald and replaced by WebSocketConnectionState Just here to avoid cluttering logs with unhandled events warnings

Parameters:

• state (aiosignald.generated.ListenerStatev1) –

• payload –

async static handle_StorageChange(event, _payload)

Parameters:

event (aiosignald.generated.StorageChangev1) –

async static handle_InternalError(event, _payload)

Parameters:

event (aiosignald.exc.InternalError) –

async handle_IncomingMessage(msg, _payload)

Dispatch a signald message to the proper session.

Can be a lot of other things than an actual message, still need to figure things out to cover all cases.

Parameters:

• msg (aiosignald.generated.IncomingMessagev1) – the data!

• _payload –

slidgnal.gateway.fmt_time(t)

Parameters:

t (Optional[float]) –

slidgnal.gateway.log