hook.access¶

class immp.hook.access.AccessPredicate¶

Bases: object

Interface for hooks to provide channel access control from a backing source.

async access_channels()¶

Request a specific set of channels to be assessed. If a separate set of channels is given by the controlling ChannelAccessHook, the intersection will be taken.

Returns:: Channels this hook is interested in providing access control for, or None to just take all channels configured upstream.
Return type:: .Channel set

async channel_access_multi(members)¶

Bulk-verify if a set of users are allowed access to all given channels.

By default, calls channel_access() for each channel-user pair, but can be overridden in order to optimise any necessary work.

Parameters:: members ((.Channel, .User set) dict) – Mapping from target channels to members awaiting verification. If None is given for a channel’s set of users, all members of the channel will be verified.
Returns:: Two sets of channel-user pairs, the first for users who are allowed, the second for those who are denied. Each pair should appear in at most one of the two lists; conflicts will be resolved to deny access.
Return type:: ((.Channel, .User) set, (.Channel, .User) set)

async channel_access(channel, user)¶

Verify if a user is allowed access to a channel.

Parameters:

channel (.Channel) – Target channel.
user (.User) – User to be verified.

Returns:

True to grant access for this user to the given channel, False to deny access, or None to abstain from a decision.

Return type:

bool

class immp.hook.access.ChannelAccessHook(name, config, host, virtual=False)¶

Bases: Hook, AccessPredicate

Hook for controlling membership of, and joins to, secure channels.

async channel_access_multi(channels, users)¶

Bulk-verify if a set of users are allowed access to all given channels.

By default, calls channel_access() for each channel-user pair, but can be overridden in order to optimise any necessary work.

Parameters:: members ((.Channel, .User set) dict) – Mapping from target channels to members awaiting verification. If None is given for a channel’s set of users, all members of the channel will be verified.
Returns:: Two sets of channel-user pairs, the first for users who are allowed, the second for those who are denied. Each pair should appear in at most one of the two lists; conflicts will be resolved to deny access.
Return type:: ((.Channel, .User) set, (.Channel, .User) set)

async channel_access(channel, user)¶

Verify if a user is allowed access to a channel.

Parameters:

channel (.Channel) – Target channel.
user (.User) – User to be verified.

Returns:

True to grant access for this user to the given channel, False to deny access, or None to abstain from a decision.

Return type:

bool

async verify(members=None)¶

Perform verification of each user in each channel, for all configured access predicates. Users who are denied access by any predicate will be removed, unless passive mode is set.

Parameters:

members ((.Channel, .User set) dict) –

Mapping from target channels to a subset of users pending verification.

If None is given for a channel’s set of users, all members present in the channel will be verified. If members itself is None, access checks will be run against all configured channels.

on_ready()¶: Perform any post-startup tasks once all hooks and plugs are ready.

async on_receive(sent, source, primary)¶

Handle an incoming message received by any plug.

Parameters:

sent (.SentMessage) – Raw message received from another plug.
source (.Message) – Original message data used to generate the raw message, if sent via the plug (e.g. from another hook), equivalent to msg if the source is otherwise unknown.
primary (bool) – False for supplementary messages if the source message required multiple raw messages in order to represent it (e.g. messages with multiple attachments where the underlying network doesn’t support it), otherwise True.