Declare new protocol capabilities: virtual-server, freeform-nicks

docs/technical/pmodule-spec.md

@@ -1,6 +1,6 @@
 # PyLink Protocol Module Specification
 
-***Last updated for 2.0.0 (2018-07-11).***
+***Last updated for 2.1-alpha2 (2019-06-23).***
 
 Starting with PyLink 2.x, a *protocol module* is any module containing a class derived from `PyLinkNetworkCore` (e.g. `InspIRCdProtocol`), along with a global `Class` attribute set equal to it (e.g. `Class = InspIRCdProtocol`). These modules do everything from managing connections to providing plugins with an API to send and receive data. New protocol modules may be implemented based off any of the classes in the following inheritance tree, with each containing a different amount of abstraction.
 
@@ -135,12 +135,16 @@ As of writing, the following protocol capabilities (case-sensitive) are implemen
 - `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)
+- `freeform-nicks` - if set, nicknames for PyLink's virtual clients are not subject to validity and nick collision checks. This implies the `slash-in-nicks` capability.
+    - Note: PyLink already allows incoming nicks to be freeform, provided they are encoded correctly and don't cause parsing conflicts (i.e. containing reserved chars on IRC)
 - `has-statusmsg` - whether STATUSMSG messages (e.g. `@#channel`) are supported
-- `has-ts` - determines whether channel and user timestamps are trackable (and not just spoofed)
+- `has-ts` - determines whether channel and user timestamps are tracked (and not 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)
+- `virtual-server` - marks the server as virtual, i.e. controlled by protocol module under a different server. Virtual servers are ignored by `rehash` and `disconnect` in the `networks` plugin.
+    - This is used by pylink-discord as of v0.2.0.
 - `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!
 
@@ -154,7 +158,7 @@ For reference, the `IRCS2SProtocol` class defines the following by default:
 - `can-track-servers`
 - `has-ts`
 
-Whereas `PyLinkNetworkCore` defines no capabilities (i.e. the empty set) by default.
+Whereas `PyLinkNetworkCore` defines no capabilities (i.e. an empty set) by default.
 
 ## PyLink structures
 In this section, `self` refers to the network object/protocol module instance itself (i.e. from its own perspective).
@@ -257,6 +261,8 @@ In short, protocol modules have some very important jobs. If any of these aren't
 7) Declare the correct set of protocol module capabilities to prevent confusing PyLink's plugins.
 
 ## Changes to this document
+* 2019-06-23 (2.1-alpha2)
+   - Added new protocol capabilities: `virtual-server` and `freeform-nicks`
 * 2018-07-11 (2.0.0)
    - Version bump for 2.0 stable release; no meaningful content changes.
 * 2018-06-26 (2.0-beta1)