GitHub/PyLink
3
0
Fork 0
mirror of https://github.com/jlu5/PyLink.git synced 2024-11-30 06:39:43 +01:00
Code Issues Projects Releases Wiki Activity

Update GitHub repository address

Browse Source
This commit is contained in:
James Lu 2018-07-08 12:53:59 -07:00
parent c1f37c2236
commit bba235bba2
10 changed files with 30 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
README.md
View File

@ -24,7 +24,7 @@ PyLink and any bundled software are licensed under the Mozilla Public License, v
**When upgrading between major versions, remember to read the [release notes](RELNOTES.md) for any breaking changes!**
Please report any bugs you find to the [issue tracker](https://github.com/GLolol/PyLink/issues). Pull requests are open if you'd like to contribute, though new stuff generally goes to the **devel** branch.
Please report any bugs you find to the [issue tracker](https://github.com/jlu5/PyLink/issues). Pull requests are open if you'd like to contribute, though new stuff generally goes to the **devel** branch.
You can also find support via our IRC channel at `#PyLink @ irc.overdrivenetworks.com `([webchat][webchatlink]). Ask your questions and be patient for a response.
@ -47,7 +47,7 @@ If you are a developer and want to help make PyLink more portable, patches are h
* *For enhanced cron support (by removing stale PID files): psutil (`pip3 install psutil`)
* *For the servprotect plugin*: expiringdict (`pip3 install expiringdict`)
2) Clone the repository: `git clone https://github.com/GLolol/PyLink && cd PyLink`
2) Clone the repository: `git clone https://github.com/jlu5/PyLink && cd PyLink`
3) Pick your branch.
* By default you'll be on the **master** branch, which contains the latest stable code. This branch is recommended for production networks that don't require new features or intensive bug fixes as they are developed.
@ -62,7 +62,7 @@ If you are a developer and want to help make PyLink more portable, patches are h
2) Run `pip3 install pylinkirc` to download and install PyLink. pip will automatically resolve dependencies.
3) Download or copy https://github.com/GLolol/PyLink/blob/master/example-conf.yml for an example configuration.
3) Download or copy https://github.com/jlu5/PyLink/blob/master/example-conf.yml for an example configuration.
### Installing via Ubuntu PPA (14.04/Trusty and above)

2
docs/automode.md
View File

@ -34,4 +34,4 @@ See the [Permissions Reference](permissions-reference.md#automode) for a list of
## Caveats
- Service bot joining and Relay don't always behave consistently: see https://github.com/GLolol/PyLink/issues/265
- Service bot joining and Relay don't always behave consistently: see https://github.com/jlu5/PyLink/issues/265

12
docs/faq.md
View File

@ -4,7 +4,7 @@
### I get errors like "ImportError: No module named 'yaml'" when I start PyLink
You are missing dependencies - re-read https://github.com/GLolol/PyLink/blob/master/README.md#installation
You are missing dependencies - re-read https://github.com/jlu5/PyLink/blob/master/README.md#installation
### I get errors like "yaml.scanner.ScannerError: while scanning for the next token, found character '\t' that cannot start any token"
@ -66,7 +66,7 @@ If these steps haven't helped you so far, maybe you've found a bug...?
### My networks keep disconnecting with SSL errors!
See https://github.com/GLolol/PyLink/issues/463 - the problem appears to be caused somewhere in Python's SSL stack and/or OpenSSL, and not directly by our code.
See https://github.com/jlu5/PyLink/issues/463 - the problem appears to be caused somewhere in Python's SSL stack and/or OpenSSL, and not directly by our code.
Unfortunately, the only workarounds so far are to either disable SSL/TLS, or wrap a plain IRC connection in an external service (stunnel, OpenVPN, etc.)
@ -80,7 +80,7 @@ PyLink does not support inbound connections - much like regular services such as
**No!** Only the PyLink administrator needs to host a PyLink instance with the `relay` plugin loaded, as each instance can connect to multiple networks. Everyone else only needs to add a link block on their IRCd.
InterJanus-style links between PyLink daemons are not supported yet; see https://github.com/GLolol/PyLink/issues/99 for any progress regarding that.
InterJanus-style links between PyLink daemons are not supported yet; see https://github.com/jlu5/PyLink/issues/99 for any progress regarding that.
### What are PyLink's advantages over Janus?
@ -99,10 +99,10 @@ However, if the nick mentioned is legal on IRC, this issue is likely caused by a
### Clientbot doesn't relay both ways!
Load the `relay_clientbot` plugin. https://github.com/GLolol/PyLink/blob/1.3-beta1/example-conf.yml#L465-L468
Load the `relay_clientbot` plugin. https://github.com/jlu5/PyLink/blob/1.3-beta1/example-conf.yml#L465-L468
### How do I turn off colors in Clientbot?
See https://github.com/GLolol/PyLink/blob/master/docs/advanced-relay-config.md#custom-clientbot-styles, especially the section "Disabling Colors/Control Codes".
See https://github.com/jlu5/PyLink/blob/master/docs/advanced-relay-config.md#custom-clientbot-styles, especially the section "Disabling Colors/Control Codes".
### Relay is occasionally dropping users from channels!
@ -115,4 +115,4 @@ This usually indicates a serious bug in either Relay or PyLink's protocol module
This indicates either a bug in PyLink's protocol module or (less commonly) a bug in your IRCd. Hint: ENDBURST is likely not being sent or received properly, which causes service bot spawning to never trigger.
Make sure you're using an [officially supported IRCd](https://github.com/GLolol/PyLink#supported-ircds) before requesting help, as custom IRCd code can potentially trigger S2S bugs and is not something we can support.
Make sure you're using an [officially supported IRCd](https://github.com/jlu5/PyLink#supported-ircds) before requesting help, as custom IRCd code can potentially trigger S2S bugs and is not something we can support.

4
docs/technical/permissions-api.md
View File

@ -16,13 +16,13 @@ from pylinkirc.coremods import permissions
Individual functions check for permissions using the `permissions.checkPermissions(irc, source, ['perm.1', 'perm.2'])` function, where the last argument is an OR'ed list of permissions matched against a list of permission string globs that a user may have. If the user has any of the permissions in the permission list, they will be allowed to call the command. This function returns `True` when a permission check passes, and raises `utils.NotAuthorizedError` when a check fails, automatically aborting the execution of the command function.
`utils.NotAuthorizedError` can be treated like any other exception, so it's possible to wrap it around `try:` / `except:` for more complex access checking ([example in the Automode plugin](https://github.com/GLolol/PyLink/blob/1.1.1/plugins/automode.py#L64-L68)).
`utils.NotAuthorizedError` can be treated like any other exception, so it's possible to wrap it around `try:` / `except:` for more complex access checking ([example in the Automode plugin](https://github.com/jlu5/PyLink/blob/1.1.1/plugins/automode.py#L64-L68)).
## Assigning default permissions
Plugins are also allowed to assign default permissions to their commands, though this should be used sparingly to ensure maximum configurability (explicitly removing permissions isn't supported yet). Default permissions are specified as a `dict` mapping targets to permission lists.
Example of this in [Automode](https://github.com/GLolol/PyLink/blob/1.1-alpha1/plugins/automode.py#L38-L39):
Example of this in [Automode](https://github.com/jlu5/PyLink/blob/1.1-alpha1/plugins/automode.py#L38-L39):
```python
# The default set of Automode permissions.

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

@ -21,7 +21,7 @@ When writing new protocol modules, it is recommended to subclass from one of the
To use `classes.IRCNetwork`, the following functions must be defined:
- `handle_events(self, data)`: given a line of text containing an IRC command, parse it and return a hook payload as specified in the [PyLink hooks reference](hooks-reference.md).
- In all of the official PyLink modules so far, handling for specific commands is delegated into submethods via [`getattr()`](https://github.com/GLolol/PyLink/blob/3922d44173593e4bcceae1218bbc6f267caa9fc1/protocols/ircs2s_common.py#L409-L412), and unknown commands are ignored.
- In all of the official PyLink modules so far, handling for specific commands is delegated into submethods via [`getattr()`](https://github.com/jlu5/PyLink/blob/3922d44173593e4bcceae1218bbc6f267caa9fc1/protocols/ircs2s_common.py#L409-L412), and unknown commands are ignored.
- `post_connect(self)`: This method sends the server introduction commands to the uplink IRC server. This method replaces the `connect()` function defined by protocol modules prior to PyLink 2.x.
- `_ping_uplink(self)`: Sends a ping command to the uplink. No return value is expected / used.
@ -53,7 +53,7 @@ For protocols that are closely related to existing ones, it may be wise to subcl
The methods defined below are integral to any protocol module, as they are needed by plugins to communicate with the rest of the world.
Unless otherwise noted, the camel-case variants of command functions (e.g. "`spawnClient`) are supported but deprecated. Protocol modules do *not* need to implement these aliases themselves; attempts to missing camel case functions are automatically coersed into their snake case variants via the [`structures.CamelCaseToSnakeCase`](https://github.com/GLolol/PyLink/blob/3922d44173593e4bcceae1218bbc6f267caa9fc1/structures.py#L172-L197) wrapper.
Unless otherwise noted, the camel-case variants of command functions (e.g. "`spawnClient`) are supported but deprecated. Protocol modules do *not* need to implement these aliases themselves; attempts to missing camel case functions are automatically coersed into their snake case variants via the [`structures.CamelCaseToSnakeCase`](https://github.com/jlu5/PyLink/blob/3922d44173593e4bcceae1218bbc6f267caa9fc1/structures.py#L172-L197) wrapper.
- **`spawn_client`**`(self, nick, ident='null', host='null', realhost=None, modes=set(), server=None, ip='0.0.0.0', realname=None, ts=None, opertype=None, manipulatable=False)` - Spawns a client on the PyLink server. No nick collision / valid nickname checks are done by protocol modules, as it is up to plugins to make sure they don't introduce anything invalid.
- `modes` is a list or set of `(mode char, mode arg)` tuples in the [PyLink mode format](#mode-formats).
@ -111,7 +111,7 @@ A protocol module should also set the following variables in each instance:
- `self.casemapping`: a string (`'rfc1459'` or `'ascii'`) to determine which case mapping the IRCd uses.
- `self.hook_map`: this is a `dict`, which maps non-standard command names sent by the IRCd to those used by [PyLink hooks](hooks-reference.md).
- Examples exist in the [UnrealIRCd](https://github.com/GLolol/PyLink/blob/1.0-beta1/protocols/unreal.py#L24-L27) and [InspIRCd](https://github.com/GLolol/PyLink/blob/1.0-beta1/protocols/inspircd.py#L25-L28) modules.
- Examples exist in the [UnrealIRCd](https://github.com/jlu5/PyLink/blob/1.0-beta1/protocols/unreal.py#L24-L27) and [InspIRCd](https://github.com/jlu5/PyLink/blob/1.0-beta1/protocols/inspircd.py#L25-L28) modules.
- `self.conf_keys`: a set of strings determining which server configuration options a protocol module needs to function; see the [Configuration key validation](#configuration-key-validation) section below.
- `self.cmodes` / `self.umodes`: These are mappings of named IRC modes (e.g. `inviteonly` or `moderated`) to a string list of mode letters, that should be either set during link negotiation or hardcoded into the protocol module. There are also special keys: `*A`, `*B`, `*C`, and `*D`, which **must** be set properly with a list of mode characters for that type of mode.
- Types of modes are defined as follows (from http://www.irc.org/tech_docs/005.html):
@ -119,8 +119,8 @@ A protocol module should also set the following variables in each instance:
- B = Mode that changes a setting and always has a parameter.
- C = Mode that changes a setting and only has a parameter when set.
- D = Mode that changes a setting and never has a parameter.
- If not defined, these will default to modes defined by RFC 1459: https://github.com/GLolol/PyLink/blob/1.0-beta1/classes.py#L127-L152
- An example of mode mapping hardcoding can be found here: https://github.com/GLolol/PyLink/blob/1.0-beta1/protocols/ts6.py#L259-L311
- If not defined, these will default to modes defined by RFC 1459: https://github.com/jlu5/PyLink/blob/1.0-beta1/classes.py#L127-L152
- An example of mode mapping hardcoding can be found here: https://github.com/jlu5/PyLink/blob/1.0-beta1/protocols/ts6.py#L259-L311
- You can find a list of supported (named) channel modes [here](channel-modes.csv), and a list of user modes [here](user-modes.csv).
- `self.prefixmodes`: This defines a mapping of prefix modes (+o, +v, etc.) to their respective mode prefix. This will default to `{'o': '@', 'v': '+'}` (the standard op and voice) if not defined.
- Example: `self.prefixmodes = {'o': '@', 'h': '%', 'v': '+'}`
@ -164,11 +164,11 @@ PyLink defines classes named `Server`, `User`, and `Channel` in the `classes` mo
- `self.servers` is a dictionary mapping server IDs (SIDs) to `Server` objects. If a protocol module does not use SIDs, servers are stored by server name instead.
- `self.users` is a dictionary mapping user IDs (UIDs) to `User` objects. If a protocol module does not use UIDs, a pseudo UID (PUID) generator such as [`classes.PUIDGenerator`](https://github.com/GLolol/PyLink/blob/3922d44173593e4bcceae1218bbc6f267caa9fc1/classes.py#L1710-L1726) *must* be used instead.
- `self.users` is a dictionary mapping user IDs (UIDs) to `User` objects. If a protocol module does not use UIDs, a pseudo UID (PUID) generator such as [`classes.PUIDGenerator`](https://github.com/jlu5/PyLink/blob/3922d44173593e4bcceae1218bbc6f267caa9fc1/classes.py#L1710-L1726) *must* be used instead.
- The rationale behind this is because plugins tracking user lists are not designed to remove and re-add users when they change their nicks.
- When sending text back to the protocol module, it may be helpful to use the [`_expandPUID()`](https://github.com/GLolol/PyLink/blob/4a363aee509c5a0488a38b9e60f93ec59a274c3c/classes.py#L1213-L1231) function in `PyLinkNetworkCoreWithUtils` to expand these pseudo-UIDs back to regular nicks.
- When sending text back to the protocol module, it may be helpful to use the [`_expandPUID()`](https://github.com/jlu5/PyLink/blob/4a363aee509c5a0488a38b9e60f93ec59a274c3c/classes.py#L1213-L1231) function in `PyLinkNetworkCoreWithUtils` to expand these pseudo-UIDs back to regular nicks.
- `self._channels` and `self.channels` are [IRC case-insensitive dictionaries](https://github.com/GLolol/PyLink/blob/4a363aee509c5a0488a38b9e60f93ec59a274c3c/structures.py#L114-L116) mapping channel names to Channel objects.
- `self._channels` and `self.channels` are [IRC case-insensitive dictionaries](https://github.com/jlu5/PyLink/blob/4a363aee509c5a0488a38b9e60f93ec59a274c3c/structures.py#L114-L116) mapping channel names to Channel objects.
- The key difference between these two dictionaries is that `_channels` is powered by `classes.ChannelState` and creates new channels *automatically* when they are accessed by index. This makes writing protocol modules easier, as they can assume that the channels they wish to modify always exist (no chance of `KeyError`!).
- `self.channels`, on the other hand, does *not* implicitly create channels and is thus better suited for plugins.
@ -206,7 +206,7 @@ Modes are stored not stored as strings, but lists of mode pairs in order to ease
Afterwords, a parsed mode list can be applied to channel name or UID using `self.apply_modes(target, parsed_modelist)`.
**Note**: for protocols that accept or reject mode changes based on TS (i.e. practically every IRCd), you will want to use [`updateTS(...)`](https://github.com/GLolol/PyLink/blob/master/classes.py#L1484-L1487) instead to only apply the modes if the source TS is lower.
**Note**: for protocols that accept or reject mode changes based on TS (i.e. practically every IRCd), you will want to use [`updateTS(...)`](https://github.com/jlu5/PyLink/blob/master/classes.py#L1484-L1487) instead to only apply the modes if the source TS is lower.
Internally, modes are stored in `Channel` and `User` objects as sets, **with the `+` prefixing each mode character omitted**. These sets are accessed via the `modes` attribute:
@ -230,13 +230,13 @@ When a certain mode (e.g. owner) isn't supported on a network, the key still exi
When receiving or sending topics, there is a `topicset` attribute in the `Channel` object that should be set to **True**. This boolean denotes that a topic has been set in the channel at least once; Relay uses it to know not to overwrite topics with empty ones during startup, when topics have not been received from all networks yet.
*Caveat:* Topic handlers on the current protocol modules do not follow TS rules (which vary by IRCd), and blindly accept data. See issue https://github.com/GLolol/PyLink/issues/277
*Caveat:* Topic handlers on the current protocol modules do not follow TS rules (which vary by IRCd), and blindly accept data. See issue https://github.com/jlu5/PyLink/issues/277
## Configuration key validation
Starting with PyLink 1.x, protocol modules can specify which config values within a server block they need in order to work. This is done by adjusting the `self.conf_keys` attribute, usually in the protocol module's `__init__()` method. The default set, defined in [`Classes.Protocol`](https://github.com/GLolol/PyLink/blob/1.0-beta1/classes.py#L1202-L1204), includes `{'ip', 'port', 'hostname', 'sid', 'sidrange', 'protocol', 'sendpass', 'recvpass'}`. Should any of these keys be missing from a server block, PyLink will bail with a configuration error.
Starting with PyLink 1.x, protocol modules can specify which config values within a server block they need in order to work. This is done by adjusting the `self.conf_keys` attribute, usually in the protocol module's `__init__()` method. The default set, defined in [`Classes.Protocol`](https://github.com/jlu5/PyLink/blob/1.0-beta1/classes.py#L1202-L1204), includes `{'ip', 'port', 'hostname', 'sid', 'sidrange', 'protocol', 'sendpass', 'recvpass'}`. Should any of these keys be missing from a server block, PyLink will bail with a configuration error.
As an example, one protocol module that tweaks this is [`Clientbot`](https://github.com/GLolol/PyLink/blob/1.0-beta1/protocols/clientbot.py#L17-L18), which removes all options except `ip`, `protocol`, and `port`.
As an example, one protocol module that tweaks this is [`Clientbot`](https://github.com/jlu5/PyLink/blob/1.0-beta1/protocols/clientbot.py#L17-L18), which removes all options except `ip`, `protocol`, and `port`.
## The final checklist

2
plugins/example.py
View File

@ -46,7 +46,7 @@ def randint(irc, source, args):
# as distinct lines in IRC.
# Note: you shouldn't make any one paragraph too long, since they may get cut off. Automatic
# word-wrap may be added in the future; see https://github.com/GLolol/PyLink/issues/153
# word-wrap may be added in the future; see https://github.com/jlu5/PyLink/issues/153
"""[<min> <max>]
Returns a random number between <min> and <max>. <min> and <max> default to 1 and 10

4
protocols/unreal.py
View File

@ -16,7 +16,7 @@ SJOIN_PREFIXES = {'q': '*', 'a': '~', 'o': '@', 'h': '%', 'v': '+', 'b': '&', 'e
class UnrealProtocol(TS6BaseProtocol):
# I'm not sure what the real limit is, but the text posted at
# https://github.com/GLolol/PyLink/issues/378 suggests 427 characters.
# https://github.com/jlu5/PyLink/issues/378 suggests 427 characters.
# https://github.com/unrealircd/unrealircd/blob/4cad9cb/src/modules/m_server.c#L1260 may
# also help. (but why BUFSIZE-*80*?) -GL
S2S_BUFSIZE = 427
@ -179,7 +179,7 @@ class UnrealProtocol(TS6BaseProtocol):
sjoin_prefix += " :"
# Wrap arguments to the max supported S2S line length to prevent cutoff
# (https://github.com/GLolol/PyLink/issues/378)
# (https://github.com/jlu5/PyLink/issues/378)
for line in utils.wrap_arguments(sjoin_prefix, itemlist, self.S2S_BUFSIZE):
self.send(line)

2
setup.py
View File

@ -44,7 +44,7 @@ setup(
long_description=long_description,
long_description_content_type='text/markdown',
url='https://github.com/GLolol/PyLink',
url='https://github.com/jlu5/PyLink',
# Author details
author='James Lu',

2
utils.py
View File

@ -497,7 +497,7 @@ class ServiceBot():
_reply(args_desc.strip())
if not shortform:
# Note: we handle newlines in docstrings a bit differently. Per
# https://github.com/GLolol/PyLink/issues/307, only double newlines (and
# https://github.com/jlu5/PyLink/issues/307, only double newlines (and
# combinations of more) have the effect of showing a new line on IRC.
# Single newlines are stripped so that word wrap can be applied in source
# code without affecting the output on IRC.

2
world.py
View File

@ -30,7 +30,7 @@ start_ts = time.time()
shutting_down = threading.Event()
# Source address.
source = "https://github.com/GLolol/PyLink" # CHANGE THIS IF YOU'RE FORKING!!
source = "https://github.com/jlu5/PyLink" # CHANGE THIS IF YOU'RE FORKING!!
# Fallback hostname used in various places internally when hostname isn't configured.
fallback_hostname = 'pylink.int'