Add changes for compatibility with WASM components and collocated UDF servers

[kesmit13]

This PR makes several changes to allow the singlestoredb work in WASM environments. Many of these changes benefit standard installations as well such as lazy loading of numpy, pandas, polars, and pyarrow. Others move imports that are only needed in certain environments, but not within WASM.

A new collocated UDF server implementation is also included that uses a high-performance loop in the C extension to parse and call Python functions on each row. This function is used both by standard collocated servers as well as WASM-based UDF handlers.

---

Note

High Risk
High risk because it introduces a new UDF server runtime (sockets, threading/process forking, dynamic registration) and makes large changes to the C extension’s serialization/execution hot path and type handling (DECIMAL/date/time/datetime).

Overview
Adds a new plugin-mode external-function server (functions/ext/plugin) that serves UDFs over a Unix socket via a CLI (python-udf-server), including a control protocol (@@health, @@functions, @@register) and thread or pre-fork process pools with live registry refresh.

Extends the C accelerator (accel.c) and rowdat_1/JSON/ASGI UDF plumbing to support DECIMAL and date/time/datetime types end-to-end, hardens buffer/length handling, and adds new fast-path helpers (call_function_accel, mmap_read, mmap_write, recv_exact) used by the plugin server.

Improves WASM/optional dependency compatibility by lazy-importing heavy libs (numpy/pandas/polars/pyarrow), moving jwt imports behind call sites, broadening MySQL default-user fallback for WASM, updating _iquery to normalize more result types (pandas/polars/arrow/numpy), and documenting the new plugin server and env vars.

^{Reviewed by Cursor Bugbot for commit 3043c59. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Copilot]

Pull request overview

This PR introduces WASM-compatibility improvements (primarily by lazy-loading heavyweight optional dependencies and moving environment-specific imports into call sites) and adds a new collocated Python UDF server implementation, including a new C-extension hot path to accelerate rowdat_1 decode → Python call → rowdat_1 encode.

Changes:

• Added a WIT interface definition and a WASM build helper script for external UDF component workflows.
• Refactored optional dependency handling (numpy/pandas/polars/pyarrow, IPython, JWT) to be more robust in constrained/WASM-like environments.
• Added a new collocated UDF server (socket + mmap protocol, thread/process modes, dynamic registration) and a C-extension accelerator entry point (call_function_accel).

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
wit/udf.wit	Defines the external UDF WIT interface and exported world.
singlestoredb/utils/_lazy_import.py	Adds cached lazy imports for heavy optional deps.
singlestoredb/utils/dtypes.py	Converts dtype maps to lazily-evaluated, cached getters.
singlestoredb/utils/results.py	Switches result formatting to lazy imports + cached type maps.
singlestoredb/utils/events.py	Broadens IPython import failure handling.
singlestoredb/converters.py	Uses lazy numpy import in vector converters.
singlestoredb/connection.py	Adjusts internal result-to-dict conversion to avoid importing pandas.
singlestoredb/mysql/connection.py	Adds WASM-friendly DEFAULT_USER detection (handles OSError).
singlestoredb/auth.py	Moves jwt import into call site.
singlestoredb/management/utils.py	Moves jwt import into call sites for WASM-friendliness.
singlestoredb/management/manager.py	Moves jwt import into is_jwt call site.
singlestoredb/functions/dtypes.py	Updates exports to use dtype-map getter functions.
singlestoredb/functions/ext/rowdat_1.py	Replaces eager dtype maps with lazy getter functions.
singlestoredb/functions/ext/json.py	Replaces eager dtype maps with lazy getter functions.
singlestoredb/functions/ext/collocated/*	Adds collocated server, protocol handling, registry, control signals, and WASM adapter.
singlestoredb/tests/test_connection.py	Makes pandas string dtype assertions version-tolerant.
resources/build_wasm.sh	Adds a build helper for wasm32-wasip2 wheels.
pyproject.toml	Adds python-udf-server CLI entry point.
accel.c	Adds call_function_accel C hot path and exports it from the extension module.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated 11 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cursor]

NEWDECIMAL added to string_types shadows decimal handler

High Severity

Value 246 (ft.NEWDECIMAL) was added to string_types, but it's also in the new decimal_types set. Since string_types is checked before decimal_types in the if-elif chains of _load, _load_vectors, _dump, and _dump_vectors, the decimal_types handler is unreachable for NEWDECIMAL. This causes NEWDECIMAL values to be returned as plain strings instead of decimal.Decimal on load, and on dump it will call .encode('utf-8') on a Decimal object, raising an AttributeError.

Additional Locations (1)

• singlestoredb/functions/ext/rowdat_1.py#L92-L93

 

^{Reviewed by Cursor Bugbot for commit a7fb74d. Configure here.}

[cursor]

PyLong key leaked in PyDict_SetItem calls

Medium Severity

PyLong_FromUnsignedLongLong(u64) returns a new reference, but PyDict_SetItem does not steal references — it increments the refcount of both key and value. The temporary PyLong key is never Py_DECREF'd, leaking memory on every non-null DECIMAL, DATE, TIME, and DATETIME/TIMESTAMP value processed through the numpy loading path (load_rowdat_1_numpy).

Additional Locations (2)

• accel.c#L2609-L2610
• accel.c#L2646-L2673

 

^{Reviewed by Cursor Bugbot for commit a7fb74d. Configure here.}

[cursor]

C TIME encoding disagrees with Python pack algorithm

High Severity

The C TIME encoding computes total_secs from days*86400 + seconds and keeps microseconds separate, then negates them independently. The Python _pack_time instead computes total microseconds via total_seconds() * 1_000_000 first, then decomposes. For negative timedeltas with non-zero microseconds (e.g., -22:59:59.5), the C approach produces a corrupted packed value because sign_v * total_us has the opposite sign from the hhmmss component, causing the packed digits to bleed. The round-trip gives a wrong timedelta.

Additional Locations (2)

• accel.c#L4990-L4998
• accel.c#L5773-L5781

 

^{Reviewed by Cursor Bugbot for commit f3d069a. Configure here.}

[cursor]

Null DECIMAL doesn't advance data past string bytes

Low Severity

In the DECIMAL handling for both load_rowdat_1_numpy (second pass) and load_rowdat_1, when is_null is true, data advances past the 8-byte length prefix but not past i64 bytes of string data. The first sizing pass always advances by both 8 and i64. If a producer ever emits a non-zero length for a null DECIMAL value, the data pointer would desync with subsequent columns and rows. Currently safe only because null encoding always uses length zero.

Additional Locations (1)

• accel.c#L4553-L4567

 

^{Reviewed by Cursor Bugbot for commit f3d069a. Configure here.}

[cursor]

NULL datetime/date/decimal crashes Python fallback deserializer

High Severity

In _load and _load_vectors, the new datetime/date/decimal deserialization runs unconditionally before the is_null check at row.append(None if is_null else val). For NULL values, the packed wire value is 0, so _unpack_datetime(0) calls datetime(0, 0, 0) which raises ValueError (year/month/day must be >= 1), _unpack_date(0) similarly crashes, and decimal.Decimal('') raises InvalidOperation. The C accelerator correctly checks is_null before unpacking, but the Python fallback does not — which is the path used in WASM, the primary target of this PR.

Additional Locations (1)

• singlestoredb/functions/ext/rowdat_1.py#L270-L287

 

^{Reviewed by Cursor Bugbot for commit 4c7fb60. Configure here.}

[cursor]

Floating-point precision loss in _pack_time for timedeltas

Low Severity

_pack_time computes int(td.total_seconds() * 1_000_000) which involves float64 arithmetic. total_seconds() returns a float, and the multiplication can lose microsecond precision for large timedelta values. Using integer-only arithmetic like td.days * 86400_000_000 + td.seconds * 1_000_000 + td.microseconds would avoid this entirely. The C code reads days, seconds, microseconds as separate integers and avoids this issue.

 

^{Reviewed by Cursor Bugbot for commit 4c7fb60. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

There are 8 total unresolved issues (including 6 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 14d5e83. Configure here.}

[cursor]

Profiling variables may be referenced before assignment on error

Low Severity

In _handle_udf_loop, when _PROFILE is True, the profiling accumulators (n_requests, t_recv, etc.) are initialized inside an if profile: block. However, if an exception occurs inside the try block before the first successful request (e.g., during get_thread_local_registry()), the finally block references n_requests which would be defined but the other timing variables would also be zero — that part is fine. But t_total computation divides by n_requests, and n_requests > 0 guards it, so this is safe. The real edge case is if profile is reassigned or shadowed unexpectedly.

 

^{Reviewed by Cursor Bugbot for commit 14d5e83. Configure here.}

[Copilot]

Pull request overview

Copilot reviewed 30 out of 30 changed files in this pull request and generated 10 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Same issue as _load(): _load_vectors() attempts decimal.Decimal(...) even when is_null is true and the encoded length is 0, which will raise decimal.InvalidOperation. Guard the decimal parsing on not is_null (or slen > 0) so NULL decimal columns can be loaded.

Suggested change

	val = decimal.Decimal(
	data_io.read(slen).decode('utf-8'),
	)
	sval = data_io.read(slen).decode('utf-8')
	val = decimal.Decimal(sval) if not is_null else sval

[Copilot]

datetime.time is normalized to 'time' here, but ROWDAT_1 TIME serialization/deserialization uses datetime.timedelta (see rowdat_1._pack_time/_unpack_time). A UDF annotated with datetime.time (or returning it) will be serialized with _pack_time() and crash because datetime.time has no total_seconds(). Either convert datetime.time to a timedelta during dump/call paths, or keep datetime.time unsupported and raise a clear error.

Suggested change

	return 'time'
	raise TypeError(
	'unsupported type annotation: datetime.time; '
	'use datetime.timedelta for TIME values, or use `args`/`returns` '
	'on the @udf/@tvf decorator to specify the data type',
	)

[Copilot]

VECTOR() validates element_type.upper() but then emits the SQL using the original element_type string. If callers pass a lowercase value (e.g. "f32"), validation passes but the SQL becomes VECTOR(n, f32) which is likely invalid. Normalize element_type = element_type.upper() before formatting the SQL string.

Suggested change

	if element_type.upper() not in (F16, F32, F64, I8, I16, I32, I64):
	element_type = element_type.upper()
	if element_type not in (F16, F32, F64, I8, I16, I32, I64):

[Copilot]

_bind_socket() unconditionally unlinks any existing path. If sock_path points to a regular file, this will delete it. Consider verifying the existing path is actually a Unix domain socket (e.g., via stat.S_ISSOCK(os.stat(...).st_mode)) before unlinking, and raise a clear error otherwise.

[Copilot]

PyDict_SetItem(py_objs, PyLong_FromUnsignedLongLong(u64), py_dec) leaks the temporary key object because PyDict_SetItem does not steal references. Create the key PyObject* separately, pass it to PyDict_SetItem, then Py_DECREF it. This matters on the hot path because it will leak one Python int per non-null DECIMAL/DATE/TIME/DATETIME cell.

[Copilot]

string_types includes 246 (MySQL NEWDECIMAL), which will cause decimal columns to be treated as strings (and binary_types will include -246). This will mis-parse/mis-dump DECIMAL/NEWDECIMAL data; remove 246 from string_types and rely on decimal_types for DECIMAL handling.

Suggested change

	string_types = set([15, 245, 246, 247, 248, 249, 250, 251, 252, 253, 254])
	string_types = set([15, 245, 247, 248, 249, 250, 251, 252, 253, 254])

[Copilot]

Decimal decoding happens even when the value is NULL. For NULL decimals _dump() writes length=0, but _load() always calls decimal.Decimal(''), which raises decimal.InvalidOperation. Skip parsing when is_null (or when slen == 0), and set val to a safe placeholder so NULLs round-trip correctly.

Suggested change

	val = decimal.Decimal(
	data_io.read(slen).decode('utf-8'),
	)
	dec_bytes = data_io.read(slen)
	if is_null or slen == 0:
	val = None
	else:
	val = decimal.Decimal(dec_bytes.decode('utf-8'))

[Copilot]

New/expanded dtype support for decimal.Decimal (and now datetime.time) isn’t covered by existing tests. Add unit tests (e.g., in singlestoredb/tests/test_udf.py::test_datetimes / a new decimal test) to assert the generated SQL/type mapping for decimal.Decimal and to define/validate expected behavior for datetime.time.

[Copilot]

Handshake reads the function name using a single recvmsg(namelen, ...) call. On a stream socket, recvmsg is allowed to return fewer than namelen bytes, which would truncate function_name and desync the protocol. Validate len(msg) == namelen (and/or handle MSG_TRUNC) and if short, read the remaining bytes (without expecting additional FDs) before decoding.

Suggested change

	if flags & getattr(socket, 'MSG_TRUNC', 0):
	logger.warning('Function name data was truncated (MSG_TRUNC)')
	return
	if len(msg) < namelen:
	remaining = _recv_exact_py(conn, namelen - len(msg))
	if remaining is None:
	logger.warning(
	'Connection closed while receiving function name',
	)
	return
	msg += remaining

[Copilot]

Dynamic function registration executes generated code inside the __main__ module. This can clobber the server’s own __main__ namespace and cause collisions between registrations/reloads. Use a dedicated/private module name for generated functions (e.g. singlestoredb.functions.ext.plugin._dynamic_udfs_<counter>), or create a fresh module per registration and keep it referenced as needed.