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.
- lingofuse/__init__.py +1075 -0
- lingofuse/_lf_native.py +1256 -0
- lingofuse/_lf_native_check.py +595 -0
- lingofuse/address.py +1082 -0
- lingofuse/async_support.py +966 -0
- lingofuse/bridge.py +1912 -0
- lingofuse/client.py +932 -0
- lingofuse/core.py +1351 -0
- lingofuse/errors.py +24 -0
- lingofuse/json_repair/__init__.py +4 -0
- lingofuse/json_repair/__main__.py +6 -0
- lingofuse/json_repair/json_parser.py +435 -0
- lingofuse/json_repair/json_repair.py +484 -0
- lingofuse/json_repair/parse_array.py +119 -0
- lingofuse/json_repair/parse_comment.py +77 -0
- lingofuse/json_repair/parse_number.py +43 -0
- lingofuse/json_repair/parse_object.py +485 -0
- lingofuse/json_repair/parse_string.py +942 -0
- lingofuse/json_repair/parse_string_helpers/__init__.py +1 -0
- lingofuse/json_repair/parse_string_helpers/object_value_context.py +115 -0
- lingofuse/json_repair/parse_string_helpers/parse_boolean_or_null.py +35 -0
- lingofuse/json_repair/parse_string_helpers/parse_json_llm_block.py +19 -0
- lingofuse/json_repair/parser_parenthesized.py +169 -0
- lingofuse/json_repair/parser_schema.py +73 -0
- lingofuse/json_repair/schema_repair.py +748 -0
- lingofuse/json_repair/utils/__init__.py +1 -0
- lingofuse/json_repair/utils/constants.py +15 -0
- lingofuse/json_repair/utils/json_context.py +78 -0
- lingofuse/json_repair/utils/object_comparer.py +47 -0
- lingofuse/json_repair/utils/pattern_properties.py +50 -0
- lingofuse/json_repair/utils/string_file_wrapper.py +183 -0
- lingofuse/json_repair_preprocess.py +352 -0
- lingofuse/lf_io.py +345 -0
- lingofuse/network_events.py +545 -0
- lingofuse/options.py +776 -0
- lingofuse/serializers.py +187 -0
- lingofuse/server.py +1174 -0
- lingofuse/test_async_support.py +855 -0
- lingofuse/test_bridge_e2e.py +735 -0
- lingofuse/test_bridge_integration.py +926 -0
- lingofuse/test_bridge_units.py +847 -0
- lingofuse/test_lingofuse.py +2413 -0
- lingofuse-1.0.0.dist-info/METADATA +1794 -0
- lingofuse-1.0.0.dist-info/RECORD +47 -0
- lingofuse-1.0.0.dist-info/WHEEL +5 -0
- lingofuse-1.0.0.dist-info/entry_points.txt +2 -0
- 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
|
+
]
|