GitHub/PyLink
3
0
Fork 0
mirror of https://github.com/jlu5/PyLink.git synced 2025-02-18 22:40:44 +01:00
Code Issues Projects Releases Wiki Activity

pmodule-spec: document protocol capabilities

Browse Source 
Closes #436.
This commit is contained in:
James Lu 2018-06-26 22:36:24 -07:00
parent bdd568f75b
commit f90ec284a4
1 changed files with 33 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
docs/technical/pmodule-spec.md
View File

@ -126,8 +126,35 @@ A protocol module should also set the following variables in each instance:
- Example: `self.prefixmodes = {'o': '@', 'h': '%', 'v': '+'}` - Example: `self.prefixmodes = {'o': '@', 'h': '%', 'v': '+'}`
- `self.connected`: this is a `threading.Event` object that plugins use to determine if the network has finished bursting. Protocol modules should set this to True via `self.connected.set()` when ready. - `self.connected`: this is a `threading.Event` object that plugins use to determine if the network has finished bursting. Protocol modules should set this to True via `self.connected.set()` when ready.
## Protocol capabilities ## PyLink Protocol capabilities
TODO PyLink 1.2 introduced the concept of protocol-defined capabilities, so that plugins wishing to use IRCd-specific features don't have to hard code protocol modules by name. Protocol capabilities are defined in `self.protocol_caps` (a set of strings) and may be changed freely before `self.connected` is set. Individual capabilities are then checked by plugins via `irc.has_cap(capability_name)`.
As of writing, the following protocol capabilities (case-sensitive) are implemented:
### Supported protocol capabilities
- `can-host-relay` - whether servers using this protocol can host a relay channel (for sanity reasons, this should be off for anything that's not IRC S2S)
- `can-spawn-clients` - determines whether any spawned clients are real or virtual (mainly for `services_support`).
- `can-track-servers` - determines whether servers are accurately tracked (for `servermaps` and other statistics)
- `has-statusmsg` - whether STATUSMSG messages (e.g. `@#channel`) are supported
- `has-ts` - determines whether channel and user timestamps are trackable (and not just spoofed)
- `slash-in-hosts` - determines whether `/` is allowed in hostnames
- `slash-in-nicks` - determines whether `/` is allowed in nicks
- `ssl-should-verify` - determines whether TLS certificates should be checked for validity by default - this should be enabled for any protocol modules needing to verify a remote server (e.g. Clientbot or a non-IRC API endpoint), and disabled for most IRC S2S links (where self-signed certs are widespread)
- `underscore-in-hosts` - determines whether `_` is allowed in client hostnames (yes, support for this actually varies by IRCd)
- `visible-state-only` - determines whether channels should be autocleared when the PyLink client leaves (for clientbot, etc.)
- Note: enabling this in a protocol module lets `coremods/handlers` automatically clean up old channels for you!
New protocol capabilities are generally added when needed - see https://github.com/jlu5/PyLink/issues/620
### Abstraction defaults
For reference, the `IRCS2SProtocol` class defines the following by default:
- `can-host-relay`
- `can-spawn-clients`
- `can-track-servers`
- `has-ts`
Whereas `PyLinkNetworkCore` defines no capabilities (i.e. the empty set) by default.
## PyLink structures ## PyLink structures
In this section, `self` refers to the network object/protocol module instance itself (i.e. from its own perspective). In this section, `self` refers to the network object/protocol module instance itself (i.e. from its own perspective).
@ -227,9 +254,12 @@ In short, protocol modules have some very important jobs. If any of these aren't
6) Check that `recvpass` is correct when applicable, and raise `ProtocolError` with a relevant error message if not. 6) Check that `recvpass` is correct when applicable, and raise `ProtocolError` with a relevant error message if not.
7) Declare the correct set of protocol module capabilities to prevent confusing PyLink's plugins.
## Changes to this document ## Changes to this document
* 2018-06-26 (2.0-beta1) * 2018-06-26 (2.0-beta1)
- Wording tweaks - Added documentation for PyLink protocol capabilities
- Wording tweaks, restructured headings
- Consistently refer to protocol module attributes as `self.<whatever>` instead of `irc.<whatever>` - Consistently refer to protocol module attributes as `self.<whatever>` instead of `irc.<whatever>`
* 2018-05-09 (2.0-alpha3) * 2018-05-09 (2.0-alpha3)
- `kill` and `kick` implementations should raise `NotImplementedError` if not supported (anti-desync measure). - `kill` and `kick` implementations should raise `NotImplementedError` if not supported (anti-desync measure).