negotiate explicitly registered IRC capabilities

(cherry picked from commit c630730a1d)

docs/plugin-api-additions/caps.md

@@ -0,0 +1,35 @@
+# Script-supported capabilities
+
+`register_capability(name, userdata=None, connection_id=None)` returns a normal
+hook handle. Register before connecting/reconnecting. Core requests the name only
+if advertised in CAP LS or CAP NEW. Existing built-in requests remain enabled;
+SASL and STS registration is rejected so scripts cannot change authentication or
+transport policy through this API. None/-1 means any connection (zero is a valid
+connection ID). Names are lowercase ASCII alphanumerics plus - . / _, 1-200 bytes.
+Duplicate registrations do not duplicate requests for an advertised token.
+
+`unhook(handle)` or script/plugin unload removes future request ownership. It
+intentionally does not disable a capability already acknowledged on a live
+connection, because another plugin/core may depend on it. Registering after CAP
+LS does not retrospectively negotiate an already-advertised capability: reconnect
+or wait for CAP NEW. Core retains ownership of CAP END; this API does not extend
+SASL waiting or delay registration awaiting plugin-only CAP ACKs.
+
+`hook_capability(name, callback, userdata=None, priority=PRI_NORM)` independently
+observes negotiation through existing raw CAP hooks. Callback receives
+`(CapabilityEvent, userdata)` with name, subcommand, value, enabled, context and
+connection_id. LS/NEW mean advertised (`enabled=None`), ACK/LIST mean enabled
+(unless a negative ACK), NAK means rejected and DEL means removed. Callback
+returns are ignored so this observer cannot eat core negotiation. Existing raw
+hooks may still eat CAP before this hook according to their normal priorities.
+
+C: `zoitechat_register_capability(ph, name, flags, connection_id, userdata)`;
+flags=0, ID=-1 for any. Check get_info("api_plugin_caps") for "1" before using
+the appended Windows slot. Use existing server CAP hooks for notifications.
+Requests are split at complete token boundaries within the existing wire limit.
+
+```python
+registration = zoitechat.register_capability('draft/example')
+zoitechat.hook_capability('draft/example', lambda event, data:
+                         event.context.prnt('{}: {}'.format(event.subcommand, event.enabled)))
+```

docs/plugin-api-additions/names.md

@@ -1,21 +0,0 @@
-# Explicit IRC comparison keys
-
-`IRCName(text, context=None, casemapping=None, connection_id=None)` is an
-immutable helper, not a str subclass. Construct it explicitly for dictionary/set
-keys; existing get_info/list/event values remain normal strings.
-Equality and hashing include the connection ID and captured casemapping, so
-identical-looking names on different connections are different keys. An IRCName
-never compares equal to a plain str. `str(key)` / `key.text` recover the spelling.
-
-`irc_casefold(text, casemapping='rfc1459')` supports ascii, strict-rfc1459 and
-rfc1459. Only ASCII IRC characters fold; Unicode casefold would be incorrect.
-The new `get_info('casemapping')` reports the comparator actually used by core.
-Current master handles ASCII and RFC1459; this patch does not change its handling
-of advertised strict-rfc1459. An explicit mapping is available for scripts that
-need strict-rfc1459 independently. Keys capture their mapping so hashes stay
-stable; rebuild a collection if the connection's mapping changes.
-
-```python
-seen = {zoitechat.IRCName('[SomeNick]')}
-assert zoitechat.IRCName('{somenick}') in seen  # RFC1459 connection
-```

plugins/python/_zoitechat_caps.py

@@ -0,0 +1,64 @@
+"""Script-owned capability requests and structured negotiation observations."""
+from collections import namedtuple
+import operator
+import _zoitechat as api
+from _zoitechat_embedded import ffi, lib
+
+__all__ = ['CapabilityEvent', 'register_capability', 'hook_capability']
+CapabilityEvent = namedtuple('CapabilityEvent',
+                            'name subcommand value enabled context connection_id')
+
+
+def register_capability(name, userdata=None, connection_id=None):
+    """Request an advertised capability on next negotiation; unhook releases ownership."""
+    connection_id = -1 if connection_id is None else operator.index(connection_id)
+    if connection_id < -1 or connection_id > 2147483647:
+        raise ValueError('connection_id must fit the C API; -1 means any')
+    plugin = api.__get_current_plugin()
+    hook = plugin.add_hook(None, userdata)
+    handle = lib.zoitechat_register_capability(lib.ph, name.encode(), 0,
+                                              connection_id, hook.handle)
+    if handle == ffi.NULL:
+        hook.is_unload = True
+        plugin.remove_hook(id(hook))
+        raise ValueError('invalid capability name, reserved capability or connection ID')
+    hook.zoitechat_hook = handle
+    return id(hook)
+
+
+def hook_capability(name, callback, userdata=None, priority=api.PRI_NORM):
+    """Observe LS/NEW/ACK/NAK/DEL/LIST; this hook does not itself request the capability."""
+    if not callable(callback):
+        raise TypeError('callback must be callable')
+
+    def dispatch(word, word_eol, data):
+        if not word_eol:
+            return api.EAT_NONE
+        line = word_eol[0]
+        if line.startswith(':'):
+            unused, separator, line = line.partition(' ')
+        parts = line.split(' ', 3)
+        if len(parts) != 4 or parts[0].upper() != 'CAP':
+            return api.EAT_NONE
+        subcommand, tokens = parts[2].upper(), parts[3]
+        if subcommand not in ('LS', 'NEW', 'ACK', 'NAK', 'DEL', 'LIST'):
+            return api.EAT_NONE
+        if tokens.startswith('* '):
+            tokens = tokens[2:]
+        tokens = tokens.lstrip(':')
+        for token in tokens.split():
+            negative = token.startswith('-')
+            cap, equals, value = token.lstrip('-').partition('=')
+            if cap != name:
+                continue
+            enabled = None
+            if subcommand in ('ACK', 'LIST'):
+                enabled = not negative
+            elif subcommand in ('DEL', 'NAK'):
+                enabled = False
+            event = CapabilityEvent(cap, subcommand, value if equals else None,
+                                    enabled, api.get_context(), api.get_prefs('id'))
+            callback(event, data)
+        return api.EAT_NONE  # observing CAP must not suppress core negotiation
+
+    return api.hook_server('CAP', dispatch, userdata, priority)

plugins/python/_zoitechat_names.py

@@ -1,74 +0,0 @@
-"""Explicit immutable IRC names; existing string-returning APIs are unchanged."""
-import _zoitechat as api
-
-__all__ = ['IRCName', 'irc_casefold']
-
-
-def irc_casefold(text, casemapping='rfc1459'):
-    """Fold ASCII IRC characters only; never apply Unicode lower()/casefold()."""
-    if casemapping not in ('ascii', 'strict-rfc1459', 'rfc1459'):
-        raise ValueError('unsupported IRC casemapping')
-    extra = {'[': '{', ']': '}', '\\': '|'} if casemapping != 'ascii' else {}
-    if casemapping == 'rfc1459':
-        extra['^'] = '~'
-    return ''.join(chr(ord(c) + 32) if 'A' <= c <= 'Z' else extra.get(c, c)
-                   for c in text)
-
-
-class IRCName:
-    """Equality/hash include connection identity and the captured casemapping."""
-    __slots__ = ('_text', '_casemapping', '_connection_id', '_key')
-
-    def __init__(self, text, context=None, casemapping=None, connection_id=None):
-        context = context or api.get_context()
-        if casemapping is None:
-            casemapping = context.get_info('casemapping')
-            if casemapping is None:
-                raise RuntimeError('host does not expose its comparison casemapping')
-        if connection_id is None:
-            previous = api.get_context()
-            if not context.set():
-                raise ValueError('context has closed')
-            try:
-                connection_id = api.get_prefs('id')
-            finally:
-                previous.set()
-        object.__setattr__(self, '_text', text)
-        object.__setattr__(self, '_casemapping', casemapping)
-        object.__setattr__(self, '_connection_id', connection_id)
-        object.__setattr__(self, '_key', (connection_id, casemapping,
-                                       irc_casefold(text, casemapping)))
-
-    def __setattr__(self, name, value):
-        raise AttributeError('IRCName is immutable')
-
-    @property
-    def text(self):
-        return self._text
-
-    @property
-    def casemapping(self):
-        return self._casemapping
-
-    @property
-    def connection_id(self):
-        return self._connection_id
-
-    def __str__(self):
-        return self._text
-
-    def __repr__(self):
-        return 'IRCName({!r}, casemapping={!r}, connection_id={!r})'.format(
-            self._text, self._casemapping, self._connection_id)
-
-    def __eq__(self, other):
-        if not isinstance(other, IRCName):
-            return NotImplemented
-        return self._key == other._key
-
-    def __ne__(self, other):
-        result = self.__eq__(other)
-        return NotImplemented if result is NotImplemented else not result
-
-    def __hash__(self):
-        return hash(self._key)

src/common/inbound.c

@@ -41,6 +41,8 @@
 #include "network.h"
 #include "notify.h"
 #include "outbound.h"
+#include <gmodule.h>
+#include "plugin.h"
 #include "inbound.h"
 #include "server.h"
 #include "servlist.h"
@@ -1980,6 +1982,22 @@ inbound_cap_ack (server *serv, char *nick, char *extensions,
 	inbound_toggle_caps (serv, extensions, TRUE);
 }
 
+/* Keep CAP REQ tokens intact and below the existing 500-byte buffer. */
+static void
+inbound_cap_request_append (server *serv, char *buffer, gsize size,
+                            const char *name, time_t timestamp)
+{
+    if (strlen (buffer) + strlen (name) + 1 >= size)
+    {
+        EMIT_SIGNAL_TIMESTAMP (XP_TE_CAPREQ, serv->server_session,
+            buffer + 9, NULL, NULL, NULL, 0, timestamp);
+        tcp_sendf (serv, "%s\r\n", g_strchomp (buffer));
+        g_strlcpy (buffer, "CAP REQ :", size);
+    }
+    g_strlcat (buffer, name, size);
+    g_strlcat (buffer, " ", size);
+}
+
 static void inbound_request_new_caps (server *serv, const char *extensions_str,
 									 const message_tags_data *tags_data);
 
@@ -2094,6 +2112,32 @@ inbound_request_new_caps (server *serv, const char *extensions_str,
 				break;
 			}
 		}
+	}
+	/* Also request plugin-owned capabilities, without repeating core requests. */
+    for (i = 0; extensions[i]; i++)
+    {
+        gsize previous;
+        gboolean builtin = FALSE;
+        for (x = 0; x < G_N_ELEMENTS (supported_caps); x++)
+        {
+            if (!strcmp (extensions[i], supported_caps[x]))
+            {
+                builtin = TRUE;
+                break;
+            }
+        }
+        if (builtin || !plugin_requests_capability (serv, extensions[i]))
+            continue;
+        for (previous = 0; previous < i; previous++)
+        {
+            if (!strcmp (extensions[previous], extensions[i]))
+                break;
+        }
+        if (previous != i)
+            continue;
+        EMIT_SIGNAL_TIMESTAMP (XP_TE_CAPREQ, serv->server_session,
+            extensions[i], NULL, NULL, NULL, 0, tags_data->timestamp);
+        tcp_sendf (serv, "CAP REQ :%s\r\n", extensions[i]);
     }
 	g_strfreev (extensions);
 }
@@ -2161,6 +2205,8 @@ inbound_cap_ls (server *serv, char *nick, char *extensions_str,
 	gboolean want_cap = FALSE; /* format the CAP REQ string based on previous capabilities being requested or not */
 	gboolean sts_upgrade_triggered = FALSE;
 	char **extensions;
+	GString *requests = g_string_new (NULL);
+	GHashTable *seen = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, NULL);
 	int i;
 
 	if (g_str_has_prefix (extensions_str, "* "))
@@ -2226,16 +2272,23 @@ inbound_cap_ls (server *serv, char *nick, char *extensions_str,
 			}
 			want_cap = TRUE;
 			serv->waiting_on_sasl = TRUE;
-			g_strlcat (buffer, "sasl ", sizeof(buffer));
+			if (g_hash_table_add (seen, g_strdup ("sasl")))
+				g_string_append (requests, "sasl ");
 			continue;
 		}
 
 		for (x = 0; x < G_N_ELEMENTS (supported_caps); ++x)
         {
             if (!g_strcmp0 (extension, supported_caps[x]))
+                break;
+        }
+        if (x < G_N_ELEMENTS (supported_caps) ||
+            plugin_requests_capability (serv, extension))
         {
-				g_strlcat (buffer, extension, sizeof(buffer));
-				g_strlcat (buffer, " ", sizeof(buffer));
+            if (g_hash_table_add (seen, g_strdup (extension)))
+            {
+                g_string_append (requests, extension);
+                g_string_append_c (requests, ' ');
                 want_cap = TRUE;
             }
         }
@@ -2245,17 +2298,30 @@ inbound_cap_ls (server *serv, char *nick, char *extensions_str,
 
 	if (sts_upgrade_triggered)
     {
+        g_hash_table_destroy (seen);
+        g_string_free (requests, TRUE);
         return;
     }
 
 	if (want_cap)
     {
-		/* buffer + 9 = emit buffer without "CAP REQ :" */
+        char **tokens = g_strsplit (requests->str, " ", 0);
+        for (i = 0; tokens[i]; i++)
+        {
+            if (tokens[i][0])
+                inbound_cap_request_append (serv, buffer, sizeof (buffer),
+                    tokens[i], tags_data->timestamp);
+        }
+        g_strfreev (tokens);
+        if (buffer[9])
+        {
             EMIT_SIGNAL_TIMESTAMP (XP_TE_CAPREQ, serv->server_session,
-									  buffer + 9, NULL, NULL, NULL, 0,
-									  tags_data->timestamp);
+                buffer + 9, NULL, NULL, NULL, 0, tags_data->timestamp);
             tcp_sendf (serv, "%s\r\n", g_strchomp (buffer));
         }
+    }
+    g_hash_table_destroy (seen);
+    g_string_free (requests, TRUE);
 	if (!serv->waiting_on_sasl && !serv->waiting_on_cap)
 	{
 		/* if we use SASL, CAP END is dealt via raw numerics */

src/common/plugin.c

@@ -99,6 +99,7 @@ struct _zoitechat_hook
 	int tag;				/* for timers & FDs only */
 	int type;			/* HOOK_* */
 	int pri;	/* fd */	/* priority / fd for HOOK_FD only */
+	int cap_connection_id;
 };
 
 struct _zoitechat_list
@@ -143,7 +144,8 @@ enum
 	HOOK_PRINT_ATTRS  = 1 << 4, /* same as above, with attributes */
 	HOOK_TIMER        = 1 << 5, /* timeouts */
 	HOOK_FD           = 1 << 6, /* sockets & fds */
-	HOOK_DELETED      = 1 << 7  /* marked for deletion */
+	HOOK_DELETED      = 1 << 7, /* marked for deletion */
+	HOOK_CAPABILITY   = 1 << 9  /* script-owned CAP requests */
 };
 
 enum
@@ -351,6 +353,7 @@ plugin_add (session *sess, char *filename, void *handle, void *init_func,
 		pl->zoitechat_emit_print_attrs = zoitechat_emit_print_attrs;
 		pl->zoitechat_event_attrs_create = zoitechat_event_attrs_create;
 		pl->zoitechat_event_attrs_free = zoitechat_event_attrs_free;
+		pl->zoitechat_register_capability = zoitechat_register_capability;
 
 		/* run zoitechat_plugin_init, if it returns 0, close the plugin */
 		if (((zoitechat_init_func *)init_func) (pl, &pl->name, &pl->desc, &pl->version, arg) == 0)
@@ -1028,6 +1031,41 @@ zoitechat_unhook (zoitechat_plugin *ph, zoitechat_hook *hook)
 	return hook->userdata;
 }
 
+zoitechat_hook *
+zoitechat_register_capability (zoitechat_plugin *ph, const char *name, int flags,
+                              int connection_id, void *userdata)
+{
+    const unsigned char *p;
+    zoitechat_hook *hook;
+    if (flags != 0 || connection_id < -1 || !name || !name[0] || strlen (name) > 200 ||
+        strcmp (name, "sasl") == 0 || strcmp (name, "sts") == 0)
+        return NULL;
+    for (p = (const unsigned char *)name; *p; p++)
+    {
+        if (!g_ascii_islower (*p) && !g_ascii_isdigit (*p) &&
+            *p != '-' && *p != '.' && *p != '/' && *p != '_')
+            return NULL;
+    }
+    hook = plugin_add_hook (ph, HOOK_CAPABILITY, 0, name, NULL, NULL, 0, userdata);
+    hook->cap_connection_id = connection_id;
+    return hook;
+}
+
+gboolean
+plugin_requests_capability (server *serv, const char *name)
+{
+    GSList *entry;
+    for (entry = hook_list; entry; entry = entry->next)
+    {
+        zoitechat_hook *hook = entry->data;
+        if (hook && hook->type == HOOK_CAPABILITY &&
+            (hook->cap_connection_id == -1 || hook->cap_connection_id == serv->id) &&
+            strcmp (hook->name, name) == 0)
+            return TRUE;
+    }
+    return FALSE;
+}
+
 zoitechat_hook *
 zoitechat_hook_command (zoitechat_plugin *ph, const char *name, int pri,
 						  zoitechat_cmd_cb *callb, const char *help_text, void *userdata)
@@ -1187,15 +1225,8 @@ zoitechat_get_info (zoitechat_plugin *ph, const char *id)
 		return text_find_format_string (e);
 	}
 
-	/* Report the comparison actually used by this connection, not an
-	 * advertised mapping that the current core does not implement. */
-	if (strcmp (id, "casemapping") == 0)
-	{
-		if (!is_session (ph->context))
-			return NULL;
-		return ph->context->server->p_cmp == g_ascii_strcasecmp
-			? "ascii" : "rfc1459";
-	}
+	if (strcmp (id, "api_plugin_caps") == 0)
+		return "1";
 
 	hash = str_hash (id);
 	/* do the session independant ones first */

src/common/plugin.h

@@ -183,6 +183,7 @@ int plugin_emit_command (session *sess, char *name, char *word[], char *word_eol
 int plugin_emit_server (session *sess, char *name, char *word[], char *word_eol[],
 						time_t server_time);
 int plugin_emit_print (session *sess, char *word[], time_t server_time);
+gboolean plugin_requests_capability (server *serv, const char *name);
 int plugin_emit_dummy_print (session *sess, char *name);
 int plugin_emit_keypress (session *sess, unsigned int state, unsigned int keyval, gunichar key);
 GList* plugin_command_list(GList *tmp_list);

src/common/zoitechat-plugin.h

@@ -206,6 +206,10 @@ struct _zoitechat_plugin
 #endif
 
 
+/* api_plugin_caps=1: register before CAP LS; flags=0, connection_id=-1 for any. */
+zoitechat_hook *zoitechat_register_capability (zoitechat_plugin *ph,
+    const char *name, int flags, int connection_id, void *userdata);
+
 zoitechat_hook *
 zoitechat_hook_command (zoitechat_plugin *ph,
 		    const char *name,
@@ -425,6 +429,7 @@ zoitechat_pluginpref_list (zoitechat_plugin *ph,
 #define zoitechat_hook_server ((ZOITECHAT_PLUGIN_HANDLE)->zoitechat_hook_server)
 #define zoitechat_hook_server_attrs ((ZOITECHAT_PLUGIN_HANDLE)->zoitechat_hook_server_attrs)
 #define zoitechat_hook_print ((ZOITECHAT_PLUGIN_HANDLE)->zoitechat_hook_print)
+#define zoitechat_register_capability ((ZOITECHAT_PLUGIN_HANDLE)->zoitechat_register_capability)
 #define zoitechat_hook_print_attrs ((ZOITECHAT_PLUGIN_HANDLE)->zoitechat_hook_print_attrs)
 #define zoitechat_hook_timer ((ZOITECHAT_PLUGIN_HANDLE)->zoitechat_hook_timer)
 #define zoitechat_hook_fd ((ZOITECHAT_PLUGIN_HANDLE)->zoitechat_hook_fd)