add opt-in asyncio task integration

(cherry picked from commit 73ccded3ac)

docs/plugin-api-additions/async.md

@@ -0,0 +1,30 @@
+# Optional Python asyncio integration
+
+`run_async(coroutine, context=None, interval=10)` returns an AsyncTask with
+`done()`, `cancel()` and `result()`. Each invocation owns a separate event loop
+pumped by an existing main-loop timer. A ready stop callback ensures selector
+polling never blocks the UI. The captured context is restored after every pump;
+a closed context cancels the work. No process-wide event-loop policy is changed.
+
+Existing synchronous scripts are unaffected. Use `asyncio.get_running_loop()`
+inside the coroutine. Child tasks use the same loop/context and are cancelled
+when the main coroutine finishes or the script unloads. Cancellation cleanup is
+bounded; tasks must not suppress cancellation indefinitely. Cleanup uses the
+captured context while it remains open; after it closes, cancellation cleanup uses
+the current valid context. Use explicit Context methods for context-specific
+output in finally blocks, and do not issue context-dependent commands there. This provides normal
+asyncio sockets/timers, not Windows subprocess support or a new HTTP library.
+Asyncio hostname resolution can use its executor; use a resolver appropriate to
+your library if you require no worker threads. Blocking work inside a coroutine
+still blocks the client and must be avoided.
+
+```python
+import asyncio
+import zoitechat
+
+async def later():
+    await asyncio.sleep(1)
+    zoitechat.prnt('Still in the context where this task was started')
+
+task = zoitechat.run_async(later())
+```

docs/plugin-api-additions/caps.md

@@ -1,35 +0,0 @@
-# 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)))
-```

plugins/python/_zoitechat_async.py

@@ -0,0 +1,100 @@
+"""Opt-in asyncio tasks pumped without blocking the client main loop."""
+import asyncio
+import operator
+import traceback
+import _zoitechat as api
+
+__all__ = ['AsyncTask', 'run_async']
+
+
+class AsyncTask:
+    """A script-owned task and isolated event loop; cancel() is cooperative."""
+    def __init__(self, coroutine, plugin, context, interval):
+        self._plugin = plugin
+        self._context = context
+        self._loop = asyncio.new_event_loop()
+        self._task = self._loop.create_task(coroutine)
+        self._closed = False
+        self._unload_hook = api.hook_unload(lambda data: self._close())
+        self._timer_hook = api.hook_timer(interval, self._tick)
+
+    def done(self):
+        return self._task.done()
+
+    def cancel(self):
+        if not self._closed:
+            return self._task.cancel()
+        return False
+
+    def result(self):
+        return self._task.result()
+
+    def _pump(self):
+        # A ready stop callback forces the selector's timeout to zero.
+        self._loop.call_soon(self._loop.stop)
+        self._loop.run_forever()
+
+    def _close(self):
+        if self._closed:
+            return
+        self._closed = True
+        previous = api.get_context()
+        self._context.set()
+        try:
+            pending = asyncio.all_tasks(self._loop)
+            for task in pending:
+                task.cancel()
+            # Bound cleanup work; tasks must cooperate with cancellation.
+            for unused in range(3):
+                if not any(not task.done() for task in pending):
+                    break
+                self._pump()
+            for task in pending:
+                if not task.done():
+                    self._loop.call_exception_handler({
+                        'message': 'Script task ignored cancellation during unload',
+                        'task': task,
+                    })
+        finally:
+            self._loop.close()
+            previous.set()
+
+    def _tick(self, userdata):
+        if self._closed:
+            return False
+        previous = api.get_context()
+        if not self._context.set():
+            self._close()
+            self._plugin.remove_hook(self._unload_hook)
+            return False
+        try:
+            self._pump()
+            if not self._task.done():
+                return True
+            try:
+                self._task.result()
+            except asyncio.CancelledError:
+                pass
+            except Exception:
+                traceback.print_exc()
+            self._close()
+            self._plugin.remove_hook(self._unload_hook)
+            return False
+        except Exception:
+            traceback.print_exc()
+            self._close()
+            self._plugin.remove_hook(self._unload_hook)
+            return False
+        finally:
+            previous.set()
+
+
+def run_async(coroutine, context=None, interval=10):
+    """Schedule a coroutine in a captured context; return an AsyncTask handle."""
+    interval = operator.index(interval)
+    if interval < 1 or interval > 2147483647:
+        raise ValueError('interval must be a positive C int in milliseconds')
+    if not asyncio.iscoroutine(coroutine):
+        raise TypeError('run_async expects a coroutine object')
+    plugin = api.__get_current_plugin()
+    return AsyncTask(coroutine, plugin, context or api.get_context(), interval)

plugins/python/_zoitechat_caps.py

@@ -1,64 +0,0 @@
-"""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)

src/common/inbound.c

@@ -41,8 +41,6 @@
 #include "network.h"
 #include "notify.h"
 #include "outbound.h"
-#include <gmodule.h>
-#include "plugin.h"
 #include "inbound.h"
 #include "server.h"
 #include "servlist.h"
@@ -1982,22 +1980,6 @@ 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);
 
@@ -2112,32 +2094,6 @@ 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);
 }
@@ -2205,8 +2161,6 @@ 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, "* "))
@@ -2272,23 +2226,16 @@ inbound_cap_ls (server *serv, char *nick, char *extensions_str,
 			}
 			want_cap = TRUE;
 			serv->waiting_on_sasl = TRUE;
-			if (g_hash_table_add (seen, g_strdup ("sasl")))
+			g_strlcat (buffer, "sasl ", sizeof(buffer));
-				g_string_append (requests, "sasl ");
 			continue;
 		}
 
-		for (x = 0; x < G_N_ELEMENTS (supported_caps); ++x)
+		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))
 			{
-            if (g_hash_table_add (seen, g_strdup (extension)))
+				g_strlcat (buffer, extension, sizeof(buffer));
-            {
+				g_strlcat (buffer, " ", sizeof(buffer));
-                g_string_append (requests, extension);
-                g_string_append_c (requests, ' ');
 				want_cap = TRUE;
 			}
 		}
@@ -2298,30 +2245,17 @@ 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)
 	{
-        char **tokens = g_strsplit (requests->str, " ", 0);
+		/* buffer + 9 = emit buffer without "CAP REQ :" */
-        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,7 +99,6 @@ 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
@@ -144,8 +143,7 @@ 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
@@ -353,7 +351,6 @@ 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)
@@ -1031,41 +1028,6 @@ 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)
@@ -1225,9 +1187,6 @@ zoitechat_get_info (zoitechat_plugin *ph, const char *id)
 		return text_find_format_string (e);
 	}
 
-	if (strcmp (id, "api_plugin_caps") == 0)
-		return "1";
-
 	hash = str_hash (id);
 	/* do the session independant ones first */
 	switch (hash)

src/common/plugin.h

@@ -183,7 +183,6 @@ 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,10 +206,6 @@ 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,
@@ -429,7 +425,6 @@ 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)