lingofuse 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. lingofuse/__init__.py +1075 -0
  2. lingofuse/_lf_native.py +1256 -0
  3. lingofuse/_lf_native_check.py +595 -0
  4. lingofuse/address.py +1082 -0
  5. lingofuse/async_support.py +966 -0
  6. lingofuse/bridge.py +1912 -0
  7. lingofuse/client.py +932 -0
  8. lingofuse/core.py +1351 -0
  9. lingofuse/errors.py +24 -0
  10. lingofuse/json_repair/__init__.py +4 -0
  11. lingofuse/json_repair/__main__.py +6 -0
  12. lingofuse/json_repair/json_parser.py +435 -0
  13. lingofuse/json_repair/json_repair.py +484 -0
  14. lingofuse/json_repair/parse_array.py +119 -0
  15. lingofuse/json_repair/parse_comment.py +77 -0
  16. lingofuse/json_repair/parse_number.py +43 -0
  17. lingofuse/json_repair/parse_object.py +485 -0
  18. lingofuse/json_repair/parse_string.py +942 -0
  19. lingofuse/json_repair/parse_string_helpers/__init__.py +1 -0
  20. lingofuse/json_repair/parse_string_helpers/object_value_context.py +115 -0
  21. lingofuse/json_repair/parse_string_helpers/parse_boolean_or_null.py +35 -0
  22. lingofuse/json_repair/parse_string_helpers/parse_json_llm_block.py +19 -0
  23. lingofuse/json_repair/parser_parenthesized.py +169 -0
  24. lingofuse/json_repair/parser_schema.py +73 -0
  25. lingofuse/json_repair/schema_repair.py +748 -0
  26. lingofuse/json_repair/utils/__init__.py +1 -0
  27. lingofuse/json_repair/utils/constants.py +15 -0
  28. lingofuse/json_repair/utils/json_context.py +78 -0
  29. lingofuse/json_repair/utils/object_comparer.py +47 -0
  30. lingofuse/json_repair/utils/pattern_properties.py +50 -0
  31. lingofuse/json_repair/utils/string_file_wrapper.py +183 -0
  32. lingofuse/json_repair_preprocess.py +352 -0
  33. lingofuse/lf_io.py +345 -0
  34. lingofuse/network_events.py +545 -0
  35. lingofuse/options.py +776 -0
  36. lingofuse/serializers.py +187 -0
  37. lingofuse/server.py +1174 -0
  38. lingofuse/test_async_support.py +855 -0
  39. lingofuse/test_bridge_e2e.py +735 -0
  40. lingofuse/test_bridge_integration.py +926 -0
  41. lingofuse/test_bridge_units.py +847 -0
  42. lingofuse/test_lingofuse.py +2413 -0
  43. lingofuse-1.0.0.dist-info/METADATA +1794 -0
  44. lingofuse-1.0.0.dist-info/RECORD +47 -0
  45. lingofuse-1.0.0.dist-info/WHEEL +5 -0
  46. lingofuse-1.0.0.dist-info/entry_points.txt +2 -0
  47. lingofuse-1.0.0.dist-info/top_level.txt +1 -0
lingofuse/__init__.py ADDED
@@ -0,0 +1,1075 @@
1
+ # -*- coding: utf-8 -*-
2
+ """
3
+ Python bindings for the LingoFuse dynamic library.
4
+
5
+ This package exposes the following high-level components:
6
+
7
+ - DataHandle: RAII wrapper for binary data buffers.
8
+ - App: Application with API registration and local execution.
9
+ - Server: Easy way to start a C4 service and expose APIs.
10
+ - C4: Client that dynamically calls remote APIs via __getattr__.
11
+ - Target / AppTarget / UIDTarget / P2PNameTarget: the three addressing
12
+ modes that the C ABI supports for remote invocation.
13
+ - NetworkEventListener / NetworkEventQueue: process-global network event
14
+ handling (since LingoFuse v3.0).
15
+ - CallFuture / AsyncBridge / await_future: modern async support
16
+ (see the "MODERN ASYNC SUPPORT" section below).
17
+ - normalize_uid / to_tp2p_uid: UID conversion utilities for callers
18
+ that need to emit UID-addressed traffic (see the
19
+ "UID NORMALIZATION UTILITIES" section below).
20
+
21
+ Additionally, module-level convenience functions:
22
+
23
+ - generate_app_name(): generates a unique name for dynamic apps.
24
+ - get_app_name(): retrieves the name from a raw AppHnd.
25
+ - set_option() / get_option(): adjust and read runtime parameters.
26
+ - get_status() / post_status(): access the internal status queue.
27
+ - check_main_thread(), check_app(), check_api(): health checks.
28
+ - check_uid(), check_uid_api(): UID health checks (v3 addressing).
29
+ - check_p2pname(), check_p2pname_api(): P2P name health checks.
30
+ - set_network_event() / clear_network_event(): install or remove
31
+ process-global network event callbacks.
32
+ - register_p2p_call(), register_p2p_notify(), unregister_p2p():
33
+ process-wide P2P API registration (independent of any App).
34
+ - repair_json_text(): the toolchain-wide JSON repair preprocessor.
35
+
36
+ All functions are thread-safe. For detailed usage, see the docstrings
37
+ in the respective modules and the Pascal import unit
38
+ (lingofuse_import.pas).
39
+
40
+ {!!!!! THREE ADDRESSING MODES !!!!!}
41
+ Remote invocation can be performed through three orthogonal addressing
42
+ modes, each with the same set of call shapes (call / async_call /
43
+ sequenced_call / notify / sequenced_notify, plus the modern
44
+ call_future / call_async / sequenced_call_future / sequenced_call_async):
45
+
46
+ client.app("MyApp").call("api", payload) # App name
47
+ client.uid(uid_bytes).call("api", payload) # UID
48
+ client.p2pname("group").notify("api", payload) # P2PName
49
+
50
+ The three addressing modes differ only in routing semantics. See
51
+ lingofuse/address.py for the full Target contract.
52
+
53
+ {!!!!! MODERN ASYNC SUPPORT !!!!!}
54
+ The modern async surface is built on two layers:
55
+
56
+ * lingofuse.async_support -- the subsystem. It owns the lifetime
57
+ of every ctypes async callback object, tracks every outstanding
58
+ operation through an explicit state machine (PENDING -> FIRED |
59
+ ABANDONED | NOT_QUEUED), and runs a background reclamation
60
+ thread. Timeouts do NOT cause use-after-free, dispatch failures
61
+ do NOT leak, and callers can distinguish "cancelled" from
62
+ "timed out".
63
+
64
+ * lingofuse.address.Target -- the user-facing API. Every Target
65
+ exposes four modern methods in addition to the legacy surface:
66
+
67
+ call_future(api, payload, timeout_ms=...) -> CallFuture
68
+ call_async(api, payload, timeout_ms=...) -> awaitable
69
+ sequenced_call_future(...) -> CallFuture
70
+ sequenced_call_async(...) -> awaitable
71
+
72
+ The Future-returning methods never block. The ``async def``
73
+ methods are suitable for use with asyncio via ``await``.
74
+
75
+ The public objects exported at package level are:
76
+
77
+ CallFuture -- concurrent.futures.Future subclass with
78
+ an ``abandoned`` flag (True when the
79
+ timeout fired before the callback arrived).
80
+
81
+ AsyncBridge -- process-wide singleton that owns every
82
+ outstanding async op. Access via
83
+ ``AsyncBridge.instance()``; diagnostic
84
+ counters via ``AsyncBridge.instance().stats()``.
85
+
86
+ await_future -- ``async def`` helper that awaits a
87
+ CallFuture from inside a coroutine. Used
88
+ internally by Target.call_async; exposed
89
+ for callers who build their own Futures.
90
+
91
+ run_async_with_future
92
+ -- low-level factory for callers who need to
93
+ issue an async request without going
94
+ through a Target. Takes an ``issue_fn``
95
+ closure and returns a CallFuture.
96
+
97
+ make_legacy_op / make_future_op
98
+ -- lower-level factory helpers used by the
99
+ legacy and modern paths respectively. Rarely
100
+ needed directly; kept public for advanced
101
+ integration.
102
+
103
+ Example::
104
+
105
+ import asyncio
106
+
107
+ from lingofuse import AppTarget
108
+
109
+ target = AppTarget("MyApp")
110
+
111
+ # Non-blocking, callback-free:
112
+ future = target.call_future("add", {"a": 1, "b": 2}, timeout_ms=3000)
113
+ result = future.result()
114
+ if future.abandoned:
115
+ print("timed out; C side may still be running")
116
+
117
+ # asyncio:
118
+ async def main():
119
+ result = await target.call_async(
120
+ "add", {"a": 1, "b": 2}, timeout_ms=3000
121
+ )
122
+ print(result)
123
+
124
+ asyncio.run(main())
125
+
126
+ The subsystem is documented in full in lingofuse/async_support.py.
127
+
128
+ {!!!!! UID NORMALIZATION UTILITIES !!!!!}
129
+ The two functions below are the supported way for a caller to prepare
130
+ a 32-byte UID for the first argument of ``LF_UID_Sequenced_Notify``,
131
+ ``LF_UID_Call``, and their siblings:
132
+
133
+ normalize_uid(uid) -> bytes
134
+ Accept a UID as bytes / bytearray / memoryview / 64-char hex
135
+ string, and return it as a 32-byte bytes object. Raises
136
+ ValueError / TypeError on malformed input.
137
+
138
+ to_tp2p_uid(uid_bytes) -> TP2P_UID
139
+ Convert the 32-byte bytes object into the ``TP2P_UID`` ctypes
140
+ array (``c_ubyte * 32``) that the LF_UID_* C ABI functions
141
+ expect as their first argument.
142
+
143
+ Both were previously private names inside ``lingofuse.address``.
144
+ They were promoted to public because the UID-addressed streaming
145
+ protocol requires EVERY service that emits a stream event to prepare
146
+ the target session's UID before calling ``LF_UID_Sequenced_Notify``.
147
+ Reaching into a private name from another package is fragile; the
148
+ public names make the dependency explicit and stable.
149
+
150
+ The private aliases ``_normalize_uid`` and ``_to_tp2p_uid`` are
151
+ retained inside ``lingofuse.address`` for backward compatibility
152
+ with code that predates this promotion (notably ``lingofuse/bridge.py``)
153
+ and are considered implementation detail. New code MUST use the
154
+ public names re-exported here.
155
+
156
+ {!!!!! PROCESS-WIDE P2P REGISTRATION !!!!!}
157
+ The module-level functions register_p2p_call / register_p2p_notify
158
+ register APIs into the process-wide P2P namespace, which is
159
+ independent of any App. Those APIs are reachable via UID addressing
160
+ or P2PName addressing without requiring the caller to know the target
161
+ App name. They are NOT reachable via App-name addressing.
162
+
163
+ In contrast, App.register_call / App.register_notify register APIs
164
+ into the app-bound namespace, reachable via App-name addressing (and
165
+ via UID addressing as well).
166
+
167
+ {!!!!! AUTO SENDER IDENTITY (SIDE DATA) !!!!!}
168
+ Every inbound request payload carries two identity fields that the
169
+ SENDER'S transport layer injects automatically before transmission
170
+ (Pascal side: TC40_LF_Client.Send_* ->
171
+ TMemory_Param_Tool.Rebuild_UID_and_P2PName):
172
+
173
+ * FromUID -- the sender's 32-byte session UID.
174
+ * FromP2PName -- the sender's user-supplied P2P group name.
175
+
176
+ These two fields are "SIDE DATA". They are NOT properties of the
177
+ handle itself. They are metadata that the sender wrote into the
178
+ payload header, and the receiver therefore sees them in the
179
+ Data_Param of the INPUT handle it receives from the framework.
180
+
181
+ Because of this design, the two reader functions:
182
+
183
+ DataHandle.get_p2p_uid() -> bytes (exactly 32 bytes)
184
+ DataHandle.get_p2p_name() -> str ('' if the sender did not set a name)
185
+
186
+ work ONLY on INPUT handles:
187
+
188
+ * Valid on the Input argument of a Call or Notify callback.
189
+ * Valid on the Input argument of a local call / notify (the
190
+ framework injects identity there too).
191
+ * INVALID on an OUTPUT handle: returns 32 zero bytes / empty
192
+ string, and logs a C-side warning.
193
+ * INVALID on a handle the caller created itself via
194
+ DataHandle(...) or DataHandle.create_permanent(...): those
195
+ handles have no "sender", so the same null result applies.
196
+
197
+ The identity is populated on ALL command paths: Call, Notify,
198
+ Sequenced_Call, Sequenced_Notify, and the UID_* / P2PName_* variants.
199
+
200
+ {!!!!! LF_Get_P2P_UID RETURNS A POINTER, NOT A VALUE !!!!!}
201
+ At the C ABI level, LF_Get_P2P_UID returns a POINTER to the 32-byte
202
+ UID (Pascal signature:
203
+
204
+ function LF_Get_P2P_UID(Hnd: TDataHnd___): PP2P_UID___;
205
+
206
+ i.e. ``^TUID___``, not ``TUID___``). The pointer is allocated by the
207
+ C side and is scheduled for automatic release about 5 seconds after
208
+ the call.
209
+
210
+ The Python high-level accessor ``DataHandle.get_p2p_uid()`` hides
211
+ this detail: it copies the 32 bytes immediately with
212
+ ``ctypes.string_at(ptr, 32)`` and returns a fresh Python ``bytes``
213
+ object. Callers of the high-level API do not see the transient
214
+ pointer.
215
+
216
+ Direct callers of the low-level binding in ``lingofuse._lf_native``
217
+ must perform the copy themselves and must NOT retain the pointer
218
+ beyond the ~5-second window, and must NOT call any deallocation
219
+ function on it.
220
+
221
+ Typical uses of the side-data accessors:
222
+
223
+ * Call admission / authorisation (compare against an allow-list).
224
+ * Audit logging (record the caller UID in hex).
225
+ * Session state (key a per-sender dict on the UID).
226
+ * Multi-tenancy (use the P2P group name as the tenant id).
227
+ * whoami probe (echo the caller's UID back to it).
228
+
229
+ See lingofuse/core.py for the full DataHandle side-data contract.
230
+
231
+ {!!!!! DATA HANDLE KINDS !!!!!}
232
+ The library provides two kinds of data handles, both wrapped by the
233
+ DataHandle class:
234
+
235
+ 1. AUTO-RECYCLED (created by the regular constructor):
236
+
237
+ dh = DataHandle('my_api')
238
+
239
+ - The handle is added to the library's idle pool.
240
+ - The pool scans the handle list periodically (default: once
241
+ every 5 seconds) and frees any handle that has been idle
242
+ (no accessor call) for longer than the configured idle
243
+ timeout (default: 10 minutes).
244
+ - Any accessor (get_size, get_pos, read_*, write_*) refreshes
245
+ the idle timestamp, postponing the timeout.
246
+ - A remote call in flight (internal calling counter > 0) also
247
+ postpones the timeout, regardless of how long the caller
248
+ holds the handle.
249
+ - The destructor calls LF_FreeData, which only marks the handle
250
+ for release; the actual release happens on the next pool
251
+ scan (at most one scan interval later).
252
+ - Recommended for the vast majority of use cases.
253
+
254
+ 2. PERMANENT (created by the classmethod `create_permanent`):
255
+
256
+ dh = DataHandle.create_permanent('my_api')
257
+
258
+ - The handle is NOT added to the library's idle pool.
259
+ - The automatic idle-timeout reclaimer will NEVER free it, no
260
+ matter how long it has been idle.
261
+ - The destructor calls LF_FreeData, which releases the record
262
+ IMMEDIATELY (synchronously).
263
+ - Recommended for handles that must survive for the entire
264
+ process lifetime (cached request templates, long-lived scratch
265
+ buffers, global registries, etc.).
266
+
267
+ Both kinds are released when LF_Shutdown is called at process exit.
268
+ See lingofuse.core.DataHandle for the full contract.
269
+
270
+ {!!!!! DATA HANDLE RECLAMATION IS CONFIGURABLE !!!!!}
271
+ The two thresholds that govern auto-recycled handles are exposed as
272
+ runtime options (see `set_option` below for the full alias list):
273
+
274
+ # Scan at most once every 5 seconds (default).
275
+ set_option('DataHandle_Pool_Scan_Interval', '5000')
276
+
277
+ # Reclaim after 10 minutes of idle time (default).
278
+ set_option('DataHandle_Idle_Timeout', '600000')
279
+
280
+ Each of these accepts a millisecond integer. A value of 0 or less
281
+ disables that side of the reclamation logic:
282
+
283
+ # Disable idle reclamation entirely. Only an explicit
284
+ # LF_FreeData / DataHandle.free() releases a handle.
285
+ set_option('DataHandle_Idle_Timeout', '0')
286
+
287
+ # Disable the scan rate limiter. The scanner runs on every
288
+ # progress tick of the simulated main thread.
289
+ set_option('DataHandle_Pool_Scan_Interval', '0')
290
+
291
+ These options do NOT affect handles created by
292
+ `DataHandle.create_permanent`: those are always released
293
+ synchronously by the wrapper's destructor and never enter the
294
+ idle-reclaim path.
295
+
296
+ {!!!!! APP LIFETIME !!!!!}
297
+ - `App.free()` detaches the application but does NOT destroy it
298
+ immediately. The underlying object remains in the global pool until
299
+ `LF.Shutdown()` is called.
300
+ - For proper resource cleanup, always call `LF.Shutdown()` or use the
301
+ `full_cleanup()` methods provided by `Server` and `C4` when you are
302
+ done.
303
+
304
+ {!!!!! NETWORK EVENT LIFETIME !!!!!}
305
+ - The network event callbacks are process-global (no per-client API).
306
+ - They run on a background C worker thread; see
307
+ `lingofuse.network_events` for the full threading contract.
308
+ - Install callbacks BEFORE `LF_PrepareDone` and clear them BEFORE
309
+ `LF_Shutdown` to avoid races and to release the Python-side strong
310
+ references held by the module.
311
+
312
+ {!!!!! JSON REPAIR PREPROCESSING !!!!!}
313
+ Every JSON read path in the toolchain (lf_io.read_json,
314
+ lf_io.read_json_or_bytes, serializers.default_deserializer,
315
+ bridge.normalize_json_bytes) routes its decoded text through
316
+ lingofuse.json_repair_preprocess.repair_json_text before it hands the
317
+ text to json.loads. The policy is a strict three-way decision:
318
+
319
+ * Valid JSON -> returned unchanged, NO log message.
320
+ * Repairable JSON -> repaired, one WARNING naming the source.
321
+ * Unrepairable -> returned unchanged, one ERROR naming the
322
+ source (on strict read paths only; the
323
+ lenient read paths suppress the error
324
+ because a non-JSON payload is a legitimate
325
+ outcome there).
326
+
327
+ The same entry point is re-exported here as `repair_json_text`, so
328
+ that advanced callers -- for example, top-level LLM services that
329
+ need to apply the exact same repair semantics to their own JSON text
330
+ -- can reuse the policy without duplicating the three-way logic.
331
+
332
+ The repair engine can be disabled globally by setting the
333
+ environment variable LINGOFUSE_JSON_REPAIR=0. When disabled, the
334
+ preprocessor only validates and never rewrites; the historical
335
+ behaviour of every read path is preserved, including the strict
336
+ readers raising on malformed input.
337
+
338
+ The repair engine itself lives in lingofuse.json_repair. Importing
339
+ lingofuse does NOT eagerly import it: the engine is loaded lazily
340
+ the first time repair_json_text encounters a malformed payload. A
341
+ deployment that strips lingofuse.json_repair will still start
342
+ cleanly, and will degrade to validation-only behaviour with a
343
+ single load-time WARNING.
344
+
345
+ {!!!!! STRING PARAMETERS !!!!!}
346
+ Every string argument passed to an LF_* function from this module is
347
+ routed through `lingofuse.lf_io.cstr`, which supplies NUL-terminated
348
+ UTF-8 bytes for the c_char_p parameter. This removes the previous
349
+ reliance on the hidden NUL byte inside CPython bytes objects and
350
+ makes the wire contract explicit.
351
+
352
+ All comments, docstrings, and log messages are in English.
353
+ """
354
+
355
+ import logging
356
+ from typing import Any, Callable, Optional
357
+
358
+ from .core import DataHandle, App, generate_app_name, get_app_name
359
+ from .server import Server
360
+ from .client import C4
361
+ from .address import (
362
+ Target,
363
+ AppTarget,
364
+ UIDTarget,
365
+ P2PNameTarget,
366
+ AsyncResultHandler,
367
+ normalize_uid,
368
+ to_tp2p_uid,
369
+ )
370
+ from .async_support import (
371
+ AsyncBridge,
372
+ AsyncOp,
373
+ CallFuture,
374
+ await_future,
375
+ make_future_op,
376
+ make_legacy_op,
377
+ run_async_with_future,
378
+ )
379
+ from .errors import (
380
+ LingoFuseError,
381
+ ConnectionError,
382
+ TimeoutError,
383
+ RegistrationError,
384
+ SerializationError,
385
+ )
386
+ from .network_events import (
387
+ set_network_event,
388
+ clear_network_event,
389
+ is_network_event_installed,
390
+ NetworkEventListener,
391
+ NetworkEventQueue,
392
+ get_network_event_queue,
393
+ )
394
+ from ._lf_native import (
395
+ LF_SetOption as _LF_SetOption,
396
+ LF_GetOption as _LF_GetOption,
397
+ )
398
+
399
+ # Unified LingoFuse payload I/O.
400
+ #
401
+ # cstr() is the single source of truth for NUL-terminated UTF-8 bytes
402
+ # for every LF_* c_char_p parameter in this package. Importing it here
403
+ # lets the convenience functions below stop hand-rolling
404
+ # `value.encode("utf-8") + b"\x00"`.
405
+ from .lf_io import cstr
406
+
407
+ # Unified JSON repair preprocessing.
408
+ #
409
+ # repair_json_text() is the single entry point for the toolchain-wide
410
+ # JSON repair policy. It is used internally by lf_io, serializers, and
411
+ # bridge, and is re-exported here so that advanced callers (for
412
+ # example, the top-level LLM services) can apply the exact same
413
+ # policy to their own JSON text without duplicating the three-way
414
+ # (valid / repairable / unrepairable) decision.
415
+ #
416
+ # This import does NOT trigger the loading of lingofuse.json_repair:
417
+ # the repair engine is loaded lazily, on the first malformed payload
418
+ # that repair_json_text sees. Importing lingofuse therefore keeps its
419
+ # historical startup cost.
420
+ from .json_repair_preprocess import repair_json_text
421
+
422
+
423
+ # Module-level logger for the process-wide P2P callback adapters.
424
+ _log = logging.getLogger("lingofuse")
425
+
426
+
427
+ # ======================================================================
428
+ # Runtime options
429
+ # ----------------------------------------------------------------------
430
+ # === Authentication ===
431
+ # - "password" / "passwd"
432
+ # Sets the C4 P2PVM authentication token (string).
433
+ #
434
+ # === Logging & Debugging ===
435
+ # - "Quiet"
436
+ # Enable/disable quiet mode (boolean). When enabled, most
437
+ # internal log messages are suppressed.
438
+ # - "ShowThreadID" / "ShowThread" / "Show_Thread"
439
+ # Show thread IDs in log output (boolean).
440
+ # - "ConsoleOutput" / "Console_Output"
441
+ # Enable or disable console logging (boolean).
442
+ #
443
+ # === Connection Readiness ===
444
+ # - "Overlap_Connection" / "Overlap_Client" / "OverlapConnection" /
445
+ # "OverlapClient" / "OverlapConnect"
446
+ # Controls whether multiple client tunnels to the same remote
447
+ # address are allowed.
448
+ # - False (default): only one tunnel per address. Subsequent
449
+ # LF_PrepareClient calls with a different appHnd will ignore
450
+ # the new appHnd.
451
+ # - True: each LF_PrepareClient call creates a new independent
452
+ # tunnel, binding the provided appHnd.
453
+ # - "Wait_Connection_ReadyOk" / "Wait_API_Prepare_Done" /
454
+ # "API_Prepare_Done_Wait" / "WaitConnect" / "Wait_Ready" /
455
+ # "WaitReady"
456
+ # If True, LF_PrepareDone blocks until all prepared clients are
457
+ # connected and their applications are online (boolean).
458
+ # Default is True. When enabled, LF_PrepareDone will not return
459
+ # until every client is fully ready, or the timeout (see below)
460
+ # expires.
461
+ # - "Wait_Connection_Timeout" / "Wait_TimeOut" /
462
+ # "API_Prepare_Done_TimeOut" / "WaitTimeOut"
463
+ # Timeout in milliseconds for the above wait (integer).
464
+ # Default is 30,000 ms (30 seconds). If the timeout is reached
465
+ # before all clients are ready, LF_PrepareDone still returns
466
+ # success (1) but some clients may be offline.
467
+ #
468
+ # === IPC (Inter-Process Communication) ===
469
+ # - "IPC_Serv_ThreadCount" / "IPC_ThreadCount" /
470
+ # "IPC_Server_ThreadCount"
471
+ # Number of threads in the IPC server thread pool (integer).
472
+ # - "IPC_Serv_MaxQueueLength" / "IPC_MaxQueueLength" /
473
+ # "IPC_Server_MaxQueueLength"
474
+ # Maximum length of the IPC message queue (integer).
475
+ # - "IPC_Serv_MaxMsgSize" / "IPC_MaxMsgSize" /
476
+ # "IPC_Server_MaxMsgSize"
477
+ # Maximum size (in bytes) of a single IPC message (integer).
478
+ #
479
+ # === Sequenced Notifications ===
480
+ # - "Fixed_Sequenced_Time" / "Fixed_Sequenced_Life"
481
+ # Idle timeout (in milliseconds) for sequenced notification
482
+ # fallback. When selecting a client for a sequenced notification,
483
+ # if the candidate with the oldest timestamp is older than this
484
+ # value, the system falls back to the newest client to avoid
485
+ # starvation (integer).
486
+ #
487
+ # === P2P Group Name ===
488
+ # - "LF_P2P_name" / "P2P_name" / "LF_P2P" / "P2P"
489
+ # The sender's user-supplied P2P group name (string). Injected
490
+ # into every outbound request payload, and reported to the
491
+ # server via the Update_UID command. Used by P2PName routing to
492
+ # dispatch a call to any client in the group.
493
+ #
494
+ # {!!!!! NOT TO BE CONFUSED WITH DataHandle.get_p2p_name !!!!!}
495
+ # This option controls the LOCAL configuration: the P2P name
496
+ # that THIS process declares for itself. It is unrelated to
497
+ # ``DataHandle.get_p2p_name()``, which reads the SENDER'S P2P
498
+ # name from the INPUT handle of a registered callback (side
499
+ # data injected by the sender's transport layer). See the
500
+ # module docstring section "AUTO SENDER IDENTITY (SIDE DATA)".
501
+ #
502
+ # === Data Handle Pool ===
503
+ # - "DataHandle_Idle_Timeout" / "Data_Idle_Timeout" / "Idle_Timeout"
504
+ # Idle timeout (in milliseconds) for automatic reclamation of
505
+ # non-permanent data handles (integer).
506
+ # > 0 : ENABLED. A tracked handle that has not been accessed
507
+ # for this long becomes a candidate for release on the
508
+ # next pool scan. Default is 600,000 ms (10 minutes).
509
+ # <= 0 : DISABLED. The idle-reclaim branch is skipped entirely;
510
+ # only an explicit LF_FreeData / DataHandle.free() call
511
+ # releases a handle.
512
+ # Any accessor call on a handle refreshes its idle timer. A
513
+ # remote call in flight (internal calling counter > 0) also
514
+ # postpones the timeout. This option does NOT affect handles
515
+ # created by DataHandle.create_permanent.
516
+ #
517
+ # - "DataHandle_Pool_Scan_Interval" / "Data_Scan_Interval" /
518
+ # "DataHandle_Scan_Interval"
519
+ # Minimum interval (in milliseconds) between two consecutive
520
+ # scans of the data-handle pool (integer).
521
+ # > 0 : ENABLED. The scanner returns immediately if fewer
522
+ # than this many milliseconds have elapsed since the
523
+ # last scan. Default is 5,000 ms (5 seconds).
524
+ # <= 0 : DISABLED. The scanner runs on every progress tick,
525
+ # without rate-limiting.
526
+ # The scanner is driven by the simulated main thread; its
527
+ # effective call frequency is bounded below by the main thread's
528
+ # tick granularity, not by this value alone.
529
+ #
530
+ # === Async Subsystem (environment variables, NOT LF_SetOption keys) ===
531
+ # - "LINGOFUSE_ASYNC_RECLAIM_GRACE"
532
+ # Seconds to keep an abandoned async op alive after its timeout
533
+ # fires, giving any in-flight C callback a chance to arrive on a
534
+ # still-valid Python object. Default: 60. Must be >= 0.
535
+ # - "LINGOFUSE_ASYNC_RECLAIM_PERIOD"
536
+ # Seconds between reclamation sweeps in the AsyncBridge
537
+ # background thread. Default: 1.0. Must be > 0.05.
538
+ # Both are read ONCE at lingofuse.async_support import time. They
539
+ # are listed here for operator discoverability only.
540
+ #
541
+ # === JSON Repair Preprocessing ===
542
+ # - Not an LF_SetOption key. Controlled by the environment variable
543
+ # LINGOFUSE_JSON_REPAIR (see lingofuse.json_repair_preprocess):
544
+ # - unset / "1" : repair is enabled (default).
545
+ # - "0" / "false" : repair is disabled; only validation runs,
546
+ # and malformed payloads are never rewritten.
547
+ # This option is listed here so that operators reading this module
548
+ # as the entry point of the package can find the full set of
549
+ # runtime controls in one place.
550
+ # ======================================================================
551
+
552
+ def set_option(option: str, value: str) -> None:
553
+ """
554
+ Adjust a runtime option.
555
+
556
+ All changes take effect immediately. Unknown options are silently
557
+ ignored. For a full list of keys, see the module docstring above
558
+ or the Pascal import unit.
559
+
560
+ Both string arguments are passed through lingofuse.lf_io.cstr,
561
+ which supplies the NUL-terminated UTF-8 bytes expected by the
562
+ underlying c_char_p parameters.
563
+ """
564
+ _LF_SetOption(cstr(option), cstr(value))
565
+
566
+
567
+ def get_option(option: str) -> str:
568
+ """
569
+ Read the current value of a runtime option.
570
+
571
+ Returns the option's current value as a UTF-8 ``str``. Unknown
572
+ option names yield an empty string, matching the underlying
573
+ library's behaviour.
574
+
575
+ The underlying LF_GetOption returns a pointer to a transient
576
+ buffer that is released ~5 seconds after the call. ctypes
577
+ automatically copies the C string into a fresh Python bytes
578
+ object on the return boundary, so the returned str is fully
579
+ detached from that buffer and safe to retain.
580
+
581
+ This function is the read-side companion of ``set_option``. Both
582
+ are routed through lingofuse.lf_io.cstr so that the wire contract
583
+ for c_char_p parameters is explicit and consistent across the
584
+ package.
585
+ """
586
+ ptr = _LF_GetOption(cstr(option))
587
+ if not ptr:
588
+ return ""
589
+ return ptr.decode("utf-8", errors="replace")
590
+
591
+
592
+ # ======================================================================
593
+ # Status and diagnostic functions
594
+ # ======================================================================
595
+
596
+ def get_status_num() -> int:
597
+ """
598
+ Return the number of pending log messages in the internal status
599
+ buffer.
600
+
601
+ The buffer holds up to 1000 messages; older ones are discarded.
602
+ """
603
+ from ._lf_native import LF_GetStatusCount
604
+ return LF_GetStatusCount()
605
+
606
+
607
+ def get_status() -> str:
608
+ """
609
+ Retrieve the next log message from the status queue.
610
+
611
+ The returned pointer is valid only until the next call to this
612
+ function. We immediately decode it to a Python string.
613
+
614
+ {!!!!! IMPORTANT !!!!!}
615
+ This function relies on the simulated main thread to process the
616
+ status queue. If the main thread is not running (i.e., before
617
+ `LF.PrepareDone` is called), the queue may be empty or stale.
618
+ Only rely on this function after the framework is fully initialised.
619
+ """
620
+ from ._lf_native import LF_GetStatus
621
+ ptr = LF_GetStatus()
622
+ if not ptr:
623
+ return ""
624
+ return ptr.decode("utf-8", errors="replace")
625
+
626
+
627
+ def post_status(status: str) -> None:
628
+ """
629
+ Inject a user-supplied message into the status queue.
630
+
631
+ This is useful for merging external logs with LingoFuse's internal
632
+ logs.
633
+
634
+ {!!!!! IMPORTANT !!!!!}
635
+ This function also relies on the main thread to process the queue.
636
+ Before `LF.PrepareDone`, messages may not appear in the buffer.
637
+
638
+ The status string is passed through lingofuse.lf_io.cstr, which
639
+ supplies the NUL-terminated UTF-8 bytes expected by the underlying
640
+ c_char_p parameter.
641
+ """
642
+ from ._lf_native import LF_PostStatus
643
+ LF_PostStatus(cstr(status))
644
+
645
+
646
+ def check_main_thread() -> bool:
647
+ """Check whether the simulated main thread is currently active."""
648
+ from ._lf_native import LF_CheckMainThread
649
+ return LF_CheckMainThread() != 0
650
+
651
+
652
+ def check_app(app_name: str) -> bool:
653
+ """
654
+ Check whether an application with the given name is available
655
+ (locally or remotely). This is a quick lookup, but may not reflect
656
+ recent changes. Useful for probing availability before a call.
657
+
658
+ The app name is passed through lingofuse.lf_io.cstr, which
659
+ supplies the NUL-terminated UTF-8 bytes expected by the underlying
660
+ c_char_p parameter.
661
+ """
662
+ from ._lf_native import LF_CheckApp
663
+ return LF_CheckApp(cstr(app_name)) != 0
664
+
665
+
666
+ def check_api(app_name: str, api_name: str) -> bool:
667
+ """
668
+ Check whether a specific API is available on the network for the
669
+ given application.
670
+
671
+ This function searches both local and remote instances of the
672
+ application to determine if the API is exported. The lookup is
673
+ based on cached information and may not reflect recent changes.
674
+ It is useful for probing availability before making a call, but
675
+ does not guarantee that the API will still be available at the
676
+ moment of the actual call.
677
+
678
+ Both string arguments are passed through lingofuse.lf_io.cstr,
679
+ which supplies the NUL-terminated UTF-8 bytes expected by the
680
+ underlying c_char_p parameters.
681
+
682
+ Args:
683
+ app_name: Application name (UTF-8, case-insensitive).
684
+ api_name: API name (UTF-8, case-insensitive).
685
+
686
+ Returns:
687
+ True if the API is available on at least one instance of the
688
+ application, False otherwise.
689
+ """
690
+ from ._lf_native import LF_CheckApi
691
+ return LF_CheckApi(cstr(app_name), cstr(api_name)) != 0
692
+
693
+
694
+ # ======================================================================
695
+ # UID / P2PName health checks
696
+ # ----------------------------------------------------------------------
697
+ # These four functions mirror check_app / check_api, but keyed on the
698
+ # other two addressing modes:
699
+ #
700
+ # * check_uid / check_uid_api -> UID addressing
701
+ # * check_p2pname / check_p2pname_api -> P2PName addressing
702
+ #
703
+ # Like check_app / check_api, all four consult a locally cached view
704
+ # of the mesh that is updated by periodic broadcasts. The cache lags
705
+ # fresh registrations and unregistrations by roughly 3 seconds, so a
706
+ # just-registered UID/P2PName may briefly return False and a
707
+ # just-unregistered one may briefly return True. Callers that need a
708
+ # definitive answer should retry, or fall back to the actual call and
709
+ # handle the empty-result case.
710
+ #
711
+ # All four functions are thread-safe and may be called at any time.
712
+ # They are meaningful only after LF_PrepareDone has been called; before
713
+ # that, they simply see an empty cache and return False.
714
+ #
715
+ # {!!!!! UID HERE IS AN ARGUMENT VALUE, NOT SIDE DATA !!!!!}
716
+ # The UID passed to check_uid / check_uid_api is a VALUE the caller
717
+ # already possesses: typically the result of a prior "whoami" probe
718
+ # or an out-of-band discovery mechanism. The C ABI declares these
719
+ # parameters as TP2P_UID___ (a 32-byte Pascal array), which ctypes
720
+ # passes by value in a cdecl call. The ctypes type used for the
721
+ # argument is therefore TP2P_UID (a c_ubyte * 32 array).
722
+ #
723
+ # This is a DIFFERENT role from the LF_Get_P2P_UID RETURN value,
724
+ # which is a POINTER to a 32-byte UID. See
725
+ # lingofuse/_lf_native.py for the full explanation of the two roles.
726
+ # ======================================================================
727
+
728
+ def _normalize_uid_for_check(uid) -> "Any":
729
+ """
730
+ Normalize the ``uid`` argument accepted by ``check_uid`` and
731
+ ``check_uid_api`` into a ``TP2P_UID`` ctypes array.
732
+
733
+ Accepted inputs:
734
+ * 32-byte bytes / bytearray / memoryview.
735
+ * 64-character hexadecimal string.
736
+
737
+ Raises ValueError / TypeError for anything else.
738
+ """
739
+ # The public UID utilities are re-exported at package level and
740
+ # also available directly from lingofuse.address. We use the
741
+ # public names here to keep the read path aligned with the rest
742
+ # of the package.
743
+ return to_tp2p_uid(normalize_uid(uid))
744
+
745
+
746
+ def check_uid(uid) -> bool:
747
+ """
748
+ Check whether a client with the given UID is currently known to
749
+ the mesh (locally or via the cached remote view).
750
+
751
+ The UID may be supplied as 32 raw bytes, a bytearray, a memoryview,
752
+ or a 64-character hexadecimal string.
753
+
754
+ Returns True if the UID is present in the local or cached remote
755
+ view, False otherwise. As with check_app, the cache may lag fresh
756
+ registrations by ~3 seconds.
757
+ """
758
+ from ._lf_native import LF_Check_UID
759
+ return LF_Check_UID(_normalize_uid_for_check(uid)) != 0
760
+
761
+
762
+ def check_uid_api(uid, api_name: str) -> bool:
763
+ """
764
+ Check whether a client with the given UID exposes the named API.
765
+
766
+ The UID may be supplied as 32 raw bytes, a bytearray, a memoryview,
767
+ or a 64-character hexadecimal string.
768
+
769
+ Returns True if the API is available on at least one client with
770
+ the matching UID, False otherwise.
771
+ """
772
+ from ._lf_native import LF_Check_UID_Api
773
+ return LF_Check_UID_Api(
774
+ _normalize_uid_for_check(uid),
775
+ cstr(api_name),
776
+ ) != 0
777
+
778
+
779
+ def check_p2pname(p2p_name: str) -> bool:
780
+ """
781
+ Check whether at least one client has the given P2P group name.
782
+
783
+ Returns True if the group is present in the local or cached remote
784
+ view, False otherwise. Cache lag applies as with check_app.
785
+ """
786
+ from ._lf_native import LF_Check_P2PNAME
787
+ return LF_Check_P2PNAME(cstr(p2p_name)) != 0
788
+
789
+
790
+ def check_p2pname_api(p2p_name: str, api_name: str) -> bool:
791
+ """
792
+ Check whether at least one client in the given P2P group exposes
793
+ the named API.
794
+
795
+ Returns True if the API is available on at least one client in
796
+ the group, False otherwise.
797
+ """
798
+ from ._lf_native import LF_Check_P2PNAME_Api
799
+ return LF_Check_P2PNAME_Api(
800
+ cstr(p2p_name),
801
+ cstr(api_name),
802
+ ) != 0
803
+
804
+
805
+ # ======================================================================
806
+ # Process-wide P2P API registration
807
+ # ----------------------------------------------------------------------
808
+ # The functions in this section register APIs into the process-wide
809
+ # P2P namespace, which is independent of any App:
810
+ #
811
+ # register_p2p_call -- register a Call API (request / response)
812
+ # register_p2p_notify -- register a Notify API (one-way)
813
+ # unregister_p2p -- remove a previously registered API
814
+ #
815
+ # APIs registered here live on the process-wide LF_P2P_APP and are
816
+ # reachable via UID addressing or P2PName addressing without requiring
817
+ # the caller to know the target App name. They are NOT reachable via
818
+ # App-name addressing, even if the registered API name happens to
819
+ # match an App name.
820
+ #
821
+ # Typical use: register a small set of globally-discoverable utility
822
+ # APIs (health probes, capability discovery, identity echo, etc.)
823
+ # that any client in the mesh can call by group name or by UID.
824
+ #
825
+ # Lifetime and keep-alive
826
+ # -----------------------
827
+ # The C library holds a raw function pointer to each installed
828
+ # callback. If the corresponding ctypes callback object is garbage
829
+ # collected while the pointer is still live, the next invocation will
830
+ # crash. We therefore keep a strong reference to every registered
831
+ # callback in the module-level ``_p2p_callbacks`` list, which is
832
+ # never cleared until process exit. This matches the contract of
833
+ # ``App._callbacks`` for app-bound registration, and is documented
834
+ # here so that the difference between the two registration paths is
835
+ # explicit.
836
+ #
837
+ # Threading
838
+ # ---------
839
+ # Registration is thread-safe and may be performed at any time, both
840
+ # before and after LF_PrepareDone. The registered callbacks run on
841
+ # TCompute worker threads, matching the contract of every other
842
+ # LingoFuse callback. They MUST NOT block, and MUST NOT call any
843
+ # synchronous LingoFuse function.
844
+ # ======================================================================
845
+
846
+ #: Strong references to every ctypes callback registered through the
847
+ #: process-wide P2P API. The list is intentionally never cleared: the
848
+ #: process-wide P2P namespace is by definition tied to the process
849
+ #: lifetime, and the underlying library does not provide a way to
850
+ #: unregister the callback object itself (only its name).
851
+ _p2p_callbacks: list = []
852
+
853
+
854
+ def register_p2p_call(
855
+ api_name: str,
856
+ func: Callable,
857
+ description: str = "",
858
+ ) -> None:
859
+ """
860
+ Register a process-wide P2P Call API.
861
+
862
+ The API becomes reachable via UID addressing or P2PName addressing
863
+ from any client in the mesh, without requiring the caller to know
864
+ the target App name. It is NOT reachable via App-name addressing.
865
+
866
+ Args:
867
+ api_name:
868
+ Unique API name within the process-wide P2P namespace.
869
+ Case-insensitive on the wire, stored as provided.
870
+ func:
871
+ The callback. Signature::
872
+
873
+ def func(trigger, inp: DataHandle, out: DataHandle) -> None:
874
+ ...
875
+
876
+ It runs on a TCompute worker thread. It MUST NOT block,
877
+ and MUST NOT call any synchronous LingoFuse function
878
+ (LF_Call / LF_Notify / LF_LocalCall / LF_PrepareDone /
879
+ LF_Shutdown), on pain of deadlock.
880
+ description:
881
+ Optional human-readable description.
882
+
883
+ Raises:
884
+ RegistrationError:
885
+ If the name is already registered in the process-wide P2P
886
+ namespace, or if the underlying library rejects the
887
+ registration for any other reason.
888
+
889
+ {!!!!! EXCEPTION ISOLATION !!!!!}
890
+ Any exception raised inside ``func`` is caught and logged to the
891
+ "lingofuse" logger. The exception never escapes into the C stack.
892
+ This mirrors the behaviour of the reference C core
893
+ (Engine.Execute_Call) and of App.register_call.
894
+
895
+ {!!!!! KEEP-ALIVE !!!!!}
896
+ The ctypes callback object wrapping ``func`` is stored in the
897
+ module-level ``_p2p_callbacks`` list and never released. This is
898
+ required: the C library holds a raw function pointer to it, and
899
+ garbage-collecting the wrapper would leave that pointer dangling.
900
+ """
901
+ # Imported lazily so that the module-level import list stays
902
+ # focused on what every user needs, and so that the low-level
903
+ # binding symbols remain visibly scoped to this function.
904
+ from ._lf_native import LF_Register_P2P_Call, LFCallFunc
905
+
906
+ def _adapter(trigger, inp, out):
907
+ # Wrap the raw ctypes handles. owned=False: the framework
908
+ # owns these handles and will release them after the callback
909
+ # returns.
910
+ h_in = DataHandle._from_raw(inp, owned=False)
911
+ h_out = DataHandle._from_raw(out, owned=False)
912
+ try:
913
+ func(trigger, h_in, h_out)
914
+ except Exception:
915
+ # Match the contract of App.register_call: never let an
916
+ # exception escape into the C stack.
917
+ _log.exception(
918
+ "P2P Call callback for API '%s' raised an exception; "
919
+ "the exception has been suppressed",
920
+ api_name,
921
+ )
922
+
923
+ c_func = LFCallFunc(_adapter)
924
+ # Keep a strong reference before the native call, so that if the
925
+ # native call itself raises (unlikely but possible on OOM), the
926
+ # wrapper still survives until the process exits.
927
+ _p2p_callbacks.append(c_func)
928
+
929
+ ret = LF_Register_P2P_Call(
930
+ cstr(api_name),
931
+ cstr(description),
932
+ None, # Trigger: unused in the Python binding.
933
+ c_func,
934
+ )
935
+ if ret != 1:
936
+ raise RegistrationError(
937
+ f"Failed to register process-wide P2P Call API "
938
+ f"'{api_name}'"
939
+ )
940
+
941
+
942
+ def register_p2p_notify(
943
+ api_name: str,
944
+ func: Callable,
945
+ description: str = "",
946
+ ) -> None:
947
+ """
948
+ Register a process-wide P2P Notify API.
949
+
950
+ The API becomes reachable via UID addressing or P2PName addressing
951
+ from any client in the mesh. It is NOT reachable via App-name
952
+ addressing.
953
+
954
+ Args:
955
+ api_name:
956
+ Unique API name within the process-wide P2P namespace.
957
+ func:
958
+ The callback. Signature::
959
+
960
+ def func(trigger, inp: DataHandle) -> None:
961
+ ...
962
+
963
+ It runs on a TCompute worker thread. It MUST NOT block,
964
+ and MUST NOT call any synchronous LingoFuse function.
965
+ description:
966
+ Optional human-readable description.
967
+
968
+ Raises:
969
+ RegistrationError:
970
+ If the name is already registered in the process-wide P2P
971
+ namespace, or if the underlying library rejects the
972
+ registration for any other reason.
973
+
974
+ {!!!!! EXCEPTION ISOLATION !!!!!}
975
+ Any exception raised inside ``func`` is caught and logged to the
976
+ "lingofuse" logger. The exception never escapes into the C stack.
977
+
978
+ {!!!!! KEEP-ALIVE !!!!!}
979
+ See register_p2p_call for the full rationale. The wrapper is kept
980
+ alive in the module-level ``_p2p_callbacks`` list.
981
+ """
982
+ from ._lf_native import LF_Register_P2P_Notify, LFNotifyFunc
983
+
984
+ def _adapter(trigger, inp):
985
+ h_in = DataHandle._from_raw(inp, owned=False)
986
+ try:
987
+ func(trigger, h_in)
988
+ except Exception:
989
+ _log.exception(
990
+ "P2P Notify callback for API '%s' raised an exception; "
991
+ "the exception has been suppressed",
992
+ api_name,
993
+ )
994
+
995
+ c_func = LFNotifyFunc(_adapter)
996
+ _p2p_callbacks.append(c_func)
997
+
998
+ ret = LF_Register_P2P_Notify(
999
+ cstr(api_name),
1000
+ cstr(description),
1001
+ None,
1002
+ c_func,
1003
+ )
1004
+ if ret != 1:
1005
+ raise RegistrationError(
1006
+ f"Failed to register process-wide P2P Notify API "
1007
+ f"'{api_name}'"
1008
+ )
1009
+
1010
+
1011
+ def unregister_p2p(api_name: str) -> bool:
1012
+ """
1013
+ Remove a previously registered process-wide P2P API.
1014
+
1015
+ The removal is immediate locally. Remote peers may still see the
1016
+ API for up to ~3 seconds until the network broadcast propagates.
1017
+
1018
+ Returns True if the API was found and removed, False otherwise.
1019
+
1020
+ Note: the corresponding ctypes callback wrapper stays in
1021
+ ``_p2p_callbacks`` even after unregistration. This is deliberate:
1022
+ the library does not expose a way to release the callback object
1023
+ itself, and keeping the reference is harmless (a few dozen bytes)
1024
+ while removing it would risk a use-after-free if the library
1025
+ still holds the pointer. Use this function only when you truly
1026
+ need to reclaim the API name; for one-shot utilities, leave the
1027
+ registration in place for the process lifetime.
1028
+ """
1029
+ from ._lf_native import LF_Unregister_P2P
1030
+ return LF_Unregister_P2P(cstr(api_name)) == 1
1031
+
1032
+
1033
+ # ======================================================================
1034
+ # Public exports
1035
+ # ======================================================================
1036
+
1037
+ __all__ = [
1038
+ # Core RAII wrappers
1039
+ "DataHandle", "App",
1040
+ # Addressing targets (three modes)
1041
+ "Target", "AppTarget", "UIDTarget", "P2PNameTarget",
1042
+ "AsyncResultHandler",
1043
+ # UID conversion utilities (public as of the current revision)
1044
+ "normalize_uid", "to_tp2p_uid",
1045
+ # Modern async support
1046
+ "AsyncBridge", "AsyncOp", "CallFuture",
1047
+ "await_future", "run_async_with_future",
1048
+ "make_legacy_op", "make_future_op",
1049
+ # Application name helpers
1050
+ "generate_app_name", "get_app_name",
1051
+ # High-level server / client
1052
+ "Server", "C4",
1053
+ # Exceptions
1054
+ "LingoFuseError", "ConnectionError", "TimeoutError",
1055
+ "RegistrationError", "SerializationError",
1056
+ # Runtime options
1057
+ "set_option", "get_option",
1058
+ # Status and diagnostics
1059
+ "get_status_num", "get_status", "post_status",
1060
+ "check_main_thread", "check_app", "check_api",
1061
+ # UID / P2PName health checks
1062
+ "check_uid", "check_uid_api",
1063
+ "check_p2pname", "check_p2pname_api",
1064
+ # Process-wide P2P API registration
1065
+ "register_p2p_call", "register_p2p_notify", "unregister_p2p",
1066
+ # Network events (since LingoFuse v3.0)
1067
+ "set_network_event",
1068
+ "clear_network_event",
1069
+ "is_network_event_installed",
1070
+ "NetworkEventListener",
1071
+ "NetworkEventQueue",
1072
+ "get_network_event_queue",
1073
+ # JSON repair preprocessing
1074
+ "repair_json_text",
1075
+ ]