uns-kit 0.2.6__tar.gz → 0.2.11__tar.gz

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 (82) hide show
  1. {uns_kit-0.2.6 → uns_kit-0.2.11}/PKG-INFO +133 -6
  2. {uns_kit-0.2.6 → uns_kit-0.2.11}/README.md +130 -5
  3. {uns_kit-0.2.6 → uns_kit-0.2.11}/pyproject.toml +3 -1
  4. uns_kit-0.2.11/src/uns_kit/MIGRATIONS.md +150 -0
  5. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/__init__.py +35 -0
  6. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/api/__init__.py +6 -0
  7. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/api/proxy.py +77 -16
  8. uns_kit-0.2.11/src/uns_kit/api/request_lifecycle.py +205 -0
  9. uns_kit-0.2.11/src/uns_kit/api/service_authority.py +87 -0
  10. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/core/__init__.py +30 -0
  11. uns_kit-0.2.11/src/uns_kit/core/async_datahub_client.py +112 -0
  12. uns_kit-0.2.11/src/uns_kit/core/async_worker.py +86 -0
  13. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/core/client.py +25 -4
  14. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/core/datahub_client.py +8 -1
  15. uns_kit-0.2.11/src/uns_kit/core/durable_input.py +279 -0
  16. uns_kit-0.2.11/src/uns_kit/core/durable_journal.py +338 -0
  17. uns_kit-0.2.11/src/uns_kit/core/http_transport.py +76 -0
  18. uns_kit-0.2.11/src/uns_kit/core/journal_handover.py +455 -0
  19. uns_kit-0.2.11/src/uns_kit/core/lifecycle.py +30 -0
  20. uns_kit-0.2.11/src/uns_kit/core/managed_input.py +219 -0
  21. uns_kit-0.2.11/src/uns_kit/core/process_work.py +54 -0
  22. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/core/proxy.py +9 -3
  23. uns_kit-0.2.11/src/uns_kit/core/proxy_process.py +600 -0
  24. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/core/proxy_process_sync.py +6 -1
  25. uns_kit-0.2.11/src/uns_kit/core/service_access.py +104 -0
  26. uns_kit-0.2.11/src/uns_kit/core/service_metadata.py +95 -0
  27. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/core/topic_builder.py +3 -0
  28. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/core/uns_mqtt_proxy.py +196 -14
  29. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/cron/proxy.py +5 -2
  30. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/database/__init__.py +3 -0
  31. uns_kit-0.2.11/src/uns_kit/database/async_client.py +78 -0
  32. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/database/client.py +6 -29
  33. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/service_bundle.py +7 -0
  34. uns_kit-0.2.6/src/uns_kit/core/proxy_process.py +0 -345
  35. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/api/data_catalog.py +0 -0
  36. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/api/event_routing.py +0 -0
  37. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/api/interfaces.py +0 -0
  38. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/cli.py +0 -0
  39. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/core/auth_client.py +0 -0
  40. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/core/config_file.py +0 -0
  41. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/core/config_schema.py +0 -0
  42. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/core/events.py +0 -0
  43. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/core/logger.py +0 -0
  44. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/core/packet.py +0 -0
  45. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/core/runtime_metadata.py +0 -0
  46. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/core/runtime_service_registration.py +0 -0
  47. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/core/secret_resolver.py +0 -0
  48. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/core/secure_store.py +0 -0
  49. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/core/service_token_provider.py +0 -0
  50. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/core/state.py +0 -0
  51. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/core/status_monitor.py +0 -0
  52. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/core/topic_matcher.py +0 -0
  53. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/core/uns_path.py +0 -0
  54. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/cron/__init__.py +0 -0
  55. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/database/params.py +0 -0
  56. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/database/schema.py +0 -0
  57. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/database/sql.py +0 -0
  58. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/database/types.py +0 -0
  59. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/templates/api/src/api_routes.py +0 -0
  60. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/templates/api/src/main.py +0 -0
  61. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/templates/azure-pipelines.yml +0 -0
  62. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/templates/cron/src/cron_example.py +0 -0
  63. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/templates/data-offer/src/api_routes.py +0 -0
  64. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/templates/data-offer/src/data_offers/__init__.py +0 -0
  65. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/templates/data-offer/src/data_offers/demo_coils.py +0 -0
  66. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/templates/data-offer/src/data_offers/demo_export.py +0 -0
  67. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/templates/data-offer/src/data_offers/sql/demo_coils.sql +0 -0
  68. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/templates/data-offer/src/data_offers/sql/demo_export.sql +0 -0
  69. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/templates/data-offer/src/main.py +0 -0
  70. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/templates/default/.gitignore +0 -0
  71. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/templates/default/README.md +0 -0
  72. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/templates/default/package.json +0 -0
  73. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/templates/default/pyproject.toml +0 -0
  74. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/templates/default/runtime.json +0 -0
  75. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/templates/default/src/config/project_config_extension.example.py +0 -0
  76. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/templates/default/src/config/project_config_extension.py +0 -0
  77. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/templates/default/src/main.py +0 -0
  78. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/templates/vscode/extensions.json +0 -0
  79. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/templates/vscode/launch.json +0 -0
  80. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/templates/vscode/settings.json +0 -0
  81. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/templates/workspace/workspace.json +0 -0
  82. {uns_kit-0.2.6 → uns_kit-0.2.11}/src/uns_kit/version.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: uns-kit
3
- Version: 0.2.6
3
+ Version: 0.2.11
4
4
  Summary: Lightweight Python UNS MQTT client (pub/sub + infra topics)
5
5
  License: MIT
6
6
  Author: Aljoša Vister
@@ -24,10 +24,12 @@ Requires-Dist: fastapi (>=0.116.1,<0.117.0) ; extra == "api"
24
24
  Requires-Dist: graypy (>=2.1.0,<3.0.0)
25
25
  Requires-Dist: infisicalsdk (>=1.0.15,<2.0.0) ; extra == "infisical"
26
26
  Requires-Dist: oracledb (>=2.5.1,<3.0.0) ; extra == "database"
27
+ Requires-Dist: paho-mqtt (>=2.1.0,<3.0.0)
27
28
  Requires-Dist: pandas (>=2.3.3,<3.0.0) ; extra == "api"
28
29
  Requires-Dist: psycopg[binary] (>=3.2.9,<4.0.0) ; extra == "database"
29
30
  Requires-Dist: pyarrow (>=21.0.0,<22.0.0) ; extra == "api"
30
31
  Requires-Dist: pyjwt[crypto] (>=2.13.0,<3.0.0) ; extra == "api"
32
+ Requires-Dist: typing-extensions (>=4.12.2,<5.0.0)
31
33
  Requires-Dist: uvicorn (>=0.35.0,<0.36.0) ; extra == "api"
32
34
  Description-Content-Type: text/markdown
33
35
 
@@ -39,6 +41,125 @@ Python UNS SDK for runtime services, API/service exposure, and Datahub access. P
39
41
  - Process + instance status topics (active/heap/uptime/alive + stats).
40
42
  - Minimal UNS packet builder/parser (data/table) aligned with TS core.
41
43
 
44
+ ## Controller API registry correction (0.2.11)
45
+
46
+ Default API metadata now uses the retained `/api-endpoints` registry topic,
47
+ matching Controller and TypeScript. This fixes missing discovery and proxy routes
48
+ caused by the earlier `/api` suffix. Handler URLs and authorization are unchanged.
49
+ The declared parent UNS topic must exist for tree-backed endpoint registration.
50
+
51
+ ## Durable input and same-host hot handover (0.2.10)
52
+
53
+ Opt-in `DurableInputJournal`, independent `DurableMqttReceiver` and `JournalInput`
54
+ commit QoS 1 input before ACK and checkpoint only after handlers and output flush.
55
+ Capacity pauses admission without pruning pending input. Unknown effects survive
56
+ restart for explicit reconciliation instead of automatic business replay.
57
+
58
+ `JournalHandover` switches one shared local journal between exact Python owners,
59
+ drains HTTP/application work, validates/restores application and output state once,
60
+ and persists operation phases. It requires private local POSIX storage and strict
61
+ QoS 1 output. Existing RAM-only inputs and legacy handover arguments are unchanged.
62
+
63
+ Read [the guide](https://github.com/uns-openhub/uns-kit/blob/master/docs/python-durable-input-handover.md) and bundled 0.2.10
64
+ migration entry. This is Python journal protocol 1; TS correlated-v2, Controller
65
+ process-group authorization, cross-host transfer and online backups remain separate.
66
+
67
+ ## Managed MQTT input and HTTP drain (0.2.9)
68
+
69
+ Managed MQTT input has one explicit async handler, bounded count/bytes, subscription
70
+ readiness and unsubscribe-before-drain. Enable it with `managedInput: true` in
71
+ `UnsParameters`, register `set_input_handler()` and await `start_input()`.
72
+ Failed input remains available for review and is never replayed automatically.
73
+
74
+ HTTP requests now remain owned through application completion, including after
75
+ disconnect. Ownership gates return retryable 503 responses on passive owners.
76
+ `drain_requests()`/Stop waits for accepted work; unknown effects block clean Stop.
77
+ Use `run_read_only_request(event, factory)` only for explicitly effect-free work.
78
+
79
+ Process Stop drains managed input and HTTP before application cleanup/output
80
+ close. Owned outputs have bounded capacity waiting and strict publish drain.
81
+ Read the bundled 0.2.9 migration entry before upgrading existing cleanup flows.
82
+ The [guide and tested examples](https://github.com/uns-openhub/uns-kit/blob/master/docs/python-managed-input-http.md)
83
+ describe local ownership, real broker/HTTP acceptance and remaining limits.
84
+
85
+ ## Service authority and async clients (0.2.8)
86
+
87
+ `AsyncUnsClient` and `create_async_database_client()` reuse the existing API/SQL
88
+ contracts through bounded worker threads, so blocking IO stays off asyncio.
89
+ The service token is reread for every authorized request. Each client serializes
90
+ operations and supports `async with` or explicit awaited `close()`.
91
+
92
+ ```python
93
+ from uns_kit import AsyncUnsClient, create_async_database_client
94
+
95
+ async with AsyncUnsClient(controller_base) as client:
96
+ history = await client.history("example/site/line/equipment/main/temperature", limit=100)
97
+
98
+ async with create_async_database_client(resolved_database_config) as database:
99
+ rows = await database.query_file("queries/read-window.sql", {"fromTs": from_time})
100
+ ```
101
+
102
+ The default async credential source is `ServiceTokenProvider`; missing service
103
+ credentials never cause implicit human login. Cancellation stops waiting while
104
+ accepted IO remains owned; close waits for it. Do not retry a possibly committed
105
+ POST/SQL operation merely because its caller timed out.
106
+
107
+ Authenticated Python API receivers now require a fresh Controller token-status
108
+ check for verified service/machine claims. Configure the trusted
109
+ `service_authorization_status_url` option or `UNS_CONTROLLER_PUBLIC_BASE`, and
110
+ require `configuredAccessAuthority: 2`. Older/unavailable status endpoints fail
111
+ closed. Configured UNS grants and unsupported Operator delegations cannot call
112
+ ordinary service APIs. Existing ordinary user JWT semantics are preserved.
113
+
114
+ Read the bundled `uns_kit/MIGRATIONS.md` before updating receivers or relying on
115
+ automatic SQL recovery: PostgreSQL/Oracle no longer replay failed operations.
116
+ See the [full guide and limits](https://github.com/uns-openhub/uns-kit/blob/master/docs/python-service-access-async.md)
117
+ and [two reference readers](https://github.com/uns-openhub/uns-kit/tree/master/examples/python-service-access).
118
+
119
+ ## Runtime and discovery parity (0.2.7)
120
+
121
+ Python now provides `ProcessWork`, opt-in `ProcessLifecycleHooks` and the same
122
+ retained service-metadata wire contract as TS. Read the bundled
123
+ `uns_kit/MIGRATIONS.md` when crossing 0.2.7, especially if you reuse process
124
+ owners after stopping or catch specific cleanup exceptions. The
125
+ [parity matrix and supported limits](https://github.com/uns-openhub/uns-kit/blob/master/docs/python-typescript-parity.md)
126
+ distinguish implemented mechanisms from planned TS capabilities.
127
+
128
+ ```python
129
+ from uns_kit import ProcessWork, ProcessLifecycleHooks
130
+
131
+ # After constructing your UnsProxyProcess, before starting application inputs:
132
+ accepted = ProcessWork(process.is_active)
133
+
134
+ def release_inputs():
135
+ # Also close your application's MQTT/HTTP input admission here.
136
+ accepted.pause()
137
+
138
+ process.register_lifecycle_participant(ProcessLifecycleHooks(
139
+ on_release=release_inputs,
140
+ drain=accepted.drain,
141
+ ))
142
+
143
+ # Background polling: await accepted.run(poll_and_publish)
144
+ # Already accepted transport input: await accepted.track(handle_message(message))
145
+ # These helpers do not limit concurrency; keep admission bounded separately.
146
+
147
+ await process.publish_service_metadata({
148
+ "serviceId": "example-processor",
149
+ "kind": "service",
150
+ "capabilities": ["telemetry-processing"],
151
+ })
152
+
153
+ # From the application's existing signal/finally cleanup path:
154
+ await process.stop() # also available as await process.shutdown()
155
+ ```
156
+
157
+ Stop first runs release hooks, then awaits accepted application work before
158
+ closing transports. Timeout does not cancel that work: another Stop awaits the
159
+ same drain. Drain failures block a clean stop. The application continues to own
160
+ signals, MQTT/HTTP admission and business resource cleanup. This does not add a
161
+ durable job queue, HTTP ownership transfer or hot handover.
162
+
42
163
  ## 0.2.0 table migration
43
164
 
44
165
  `UnsPacket.table()` now emits MQTT packet version `2.0.0` and named object
@@ -529,9 +650,15 @@ When created inside this monorepo, `pyproject.toml` is automatically set to use
529
650
  - Packet shape mirrors the TypeScript core: `{"version":"1.3.0","message":{"data":{...}},"sequenceId":0}`.
530
651
  - Windows: the library sets `WindowsSelectorEventLoopPolicy()` to avoid `add_reader/add_writer` `NotImplementedError`.
531
652
 
532
- ## TODO (parity with TS core)
533
- - Handover manager parity: subscribe to wildcard `active` and `handover` topics, keep new instances passive until timeout or handover completion, and support `handover_intent`, `handover_request`, `handover_subscriber`, `handover_fin`, and `handover_ack`.
534
- - Publish throttling / queue parity: add buffered ordered publishing instead of direct proxy-path publish, plus publisher/subscriber active-passive controls and passive-drain behavior.
535
- - Status parity: add process-level `alive` and `uptime`, publisher/subscriber active flags everywhere, published/subscribed message count and byte metrics, and process identity on active status packets.
536
- - Optional: dictionary/measurement helpers + CLI wrapper.
653
+ ## Remaining parity work
654
+
655
+ See the [current comparison and sequence](https://github.com/uns-openhub/uns-kit/blob/master/docs/python-typescript-parity.md).
656
+ The 0.2.8 slice adds ordinary service-authority checking and asynchronous client
657
+ and database facades. The 0.2.9 slice adds managed MQTT input and HTTP ownership/
658
+ drain. Operator API and host-backed stateful transitions remain future work.
659
+ The 0.2.10 slice adds same-host Python journal handover and durable input.
660
+ TS handover transport, persistent Runtime output, retained stores and process groups
661
+ need separate versioned implementations and host acceptance. The existing
662
+ `handover` argument is currently a compatibility parameter, not an implemented
663
+ handover manager. Bounded RAM publishing and flush/drain already exist.
537
664
 
@@ -6,6 +6,125 @@ Python UNS SDK for runtime services, API/service exposure, and Datahub access. P
6
6
  - Process + instance status topics (active/heap/uptime/alive + stats).
7
7
  - Minimal UNS packet builder/parser (data/table) aligned with TS core.
8
8
 
9
+ ## Controller API registry correction (0.2.11)
10
+
11
+ Default API metadata now uses the retained `/api-endpoints` registry topic,
12
+ matching Controller and TypeScript. This fixes missing discovery and proxy routes
13
+ caused by the earlier `/api` suffix. Handler URLs and authorization are unchanged.
14
+ The declared parent UNS topic must exist for tree-backed endpoint registration.
15
+
16
+ ## Durable input and same-host hot handover (0.2.10)
17
+
18
+ Opt-in `DurableInputJournal`, independent `DurableMqttReceiver` and `JournalInput`
19
+ commit QoS 1 input before ACK and checkpoint only after handlers and output flush.
20
+ Capacity pauses admission without pruning pending input. Unknown effects survive
21
+ restart for explicit reconciliation instead of automatic business replay.
22
+
23
+ `JournalHandover` switches one shared local journal between exact Python owners,
24
+ drains HTTP/application work, validates/restores application and output state once,
25
+ and persists operation phases. It requires private local POSIX storage and strict
26
+ QoS 1 output. Existing RAM-only inputs and legacy handover arguments are unchanged.
27
+
28
+ Read [the guide](https://github.com/uns-openhub/uns-kit/blob/master/docs/python-durable-input-handover.md) and bundled 0.2.10
29
+ migration entry. This is Python journal protocol 1; TS correlated-v2, Controller
30
+ process-group authorization, cross-host transfer and online backups remain separate.
31
+
32
+ ## Managed MQTT input and HTTP drain (0.2.9)
33
+
34
+ Managed MQTT input has one explicit async handler, bounded count/bytes, subscription
35
+ readiness and unsubscribe-before-drain. Enable it with `managedInput: true` in
36
+ `UnsParameters`, register `set_input_handler()` and await `start_input()`.
37
+ Failed input remains available for review and is never replayed automatically.
38
+
39
+ HTTP requests now remain owned through application completion, including after
40
+ disconnect. Ownership gates return retryable 503 responses on passive owners.
41
+ `drain_requests()`/Stop waits for accepted work; unknown effects block clean Stop.
42
+ Use `run_read_only_request(event, factory)` only for explicitly effect-free work.
43
+
44
+ Process Stop drains managed input and HTTP before application cleanup/output
45
+ close. Owned outputs have bounded capacity waiting and strict publish drain.
46
+ Read the bundled 0.2.9 migration entry before upgrading existing cleanup flows.
47
+ The [guide and tested examples](https://github.com/uns-openhub/uns-kit/blob/master/docs/python-managed-input-http.md)
48
+ describe local ownership, real broker/HTTP acceptance and remaining limits.
49
+
50
+ ## Service authority and async clients (0.2.8)
51
+
52
+ `AsyncUnsClient` and `create_async_database_client()` reuse the existing API/SQL
53
+ contracts through bounded worker threads, so blocking IO stays off asyncio.
54
+ The service token is reread for every authorized request. Each client serializes
55
+ operations and supports `async with` or explicit awaited `close()`.
56
+
57
+ ```python
58
+ from uns_kit import AsyncUnsClient, create_async_database_client
59
+
60
+ async with AsyncUnsClient(controller_base) as client:
61
+ history = await client.history("example/site/line/equipment/main/temperature", limit=100)
62
+
63
+ async with create_async_database_client(resolved_database_config) as database:
64
+ rows = await database.query_file("queries/read-window.sql", {"fromTs": from_time})
65
+ ```
66
+
67
+ The default async credential source is `ServiceTokenProvider`; missing service
68
+ credentials never cause implicit human login. Cancellation stops waiting while
69
+ accepted IO remains owned; close waits for it. Do not retry a possibly committed
70
+ POST/SQL operation merely because its caller timed out.
71
+
72
+ Authenticated Python API receivers now require a fresh Controller token-status
73
+ check for verified service/machine claims. Configure the trusted
74
+ `service_authorization_status_url` option or `UNS_CONTROLLER_PUBLIC_BASE`, and
75
+ require `configuredAccessAuthority: 2`. Older/unavailable status endpoints fail
76
+ closed. Configured UNS grants and unsupported Operator delegations cannot call
77
+ ordinary service APIs. Existing ordinary user JWT semantics are preserved.
78
+
79
+ Read the bundled `uns_kit/MIGRATIONS.md` before updating receivers or relying on
80
+ automatic SQL recovery: PostgreSQL/Oracle no longer replay failed operations.
81
+ See the [full guide and limits](https://github.com/uns-openhub/uns-kit/blob/master/docs/python-service-access-async.md)
82
+ and [two reference readers](https://github.com/uns-openhub/uns-kit/tree/master/examples/python-service-access).
83
+
84
+ ## Runtime and discovery parity (0.2.7)
85
+
86
+ Python now provides `ProcessWork`, opt-in `ProcessLifecycleHooks` and the same
87
+ retained service-metadata wire contract as TS. Read the bundled
88
+ `uns_kit/MIGRATIONS.md` when crossing 0.2.7, especially if you reuse process
89
+ owners after stopping or catch specific cleanup exceptions. The
90
+ [parity matrix and supported limits](https://github.com/uns-openhub/uns-kit/blob/master/docs/python-typescript-parity.md)
91
+ distinguish implemented mechanisms from planned TS capabilities.
92
+
93
+ ```python
94
+ from uns_kit import ProcessWork, ProcessLifecycleHooks
95
+
96
+ # After constructing your UnsProxyProcess, before starting application inputs:
97
+ accepted = ProcessWork(process.is_active)
98
+
99
+ def release_inputs():
100
+ # Also close your application's MQTT/HTTP input admission here.
101
+ accepted.pause()
102
+
103
+ process.register_lifecycle_participant(ProcessLifecycleHooks(
104
+ on_release=release_inputs,
105
+ drain=accepted.drain,
106
+ ))
107
+
108
+ # Background polling: await accepted.run(poll_and_publish)
109
+ # Already accepted transport input: await accepted.track(handle_message(message))
110
+ # These helpers do not limit concurrency; keep admission bounded separately.
111
+
112
+ await process.publish_service_metadata({
113
+ "serviceId": "example-processor",
114
+ "kind": "service",
115
+ "capabilities": ["telemetry-processing"],
116
+ })
117
+
118
+ # From the application's existing signal/finally cleanup path:
119
+ await process.stop() # also available as await process.shutdown()
120
+ ```
121
+
122
+ Stop first runs release hooks, then awaits accepted application work before
123
+ closing transports. Timeout does not cancel that work: another Stop awaits the
124
+ same drain. Drain failures block a clean stop. The application continues to own
125
+ signals, MQTT/HTTP admission and business resource cleanup. This does not add a
126
+ durable job queue, HTTP ownership transfer or hot handover.
127
+
9
128
  ## 0.2.0 table migration
10
129
 
11
130
  `UnsPacket.table()` now emits MQTT packet version `2.0.0` and named object
@@ -496,8 +615,14 @@ When created inside this monorepo, `pyproject.toml` is automatically set to use
496
615
  - Packet shape mirrors the TypeScript core: `{"version":"1.3.0","message":{"data":{...}},"sequenceId":0}`.
497
616
  - Windows: the library sets `WindowsSelectorEventLoopPolicy()` to avoid `add_reader/add_writer` `NotImplementedError`.
498
617
 
499
- ## TODO (parity with TS core)
500
- - Handover manager parity: subscribe to wildcard `active` and `handover` topics, keep new instances passive until timeout or handover completion, and support `handover_intent`, `handover_request`, `handover_subscriber`, `handover_fin`, and `handover_ack`.
501
- - Publish throttling / queue parity: add buffered ordered publishing instead of direct proxy-path publish, plus publisher/subscriber active-passive controls and passive-drain behavior.
502
- - Status parity: add process-level `alive` and `uptime`, publisher/subscriber active flags everywhere, published/subscribed message count and byte metrics, and process identity on active status packets.
503
- - Optional: dictionary/measurement helpers + CLI wrapper.
618
+ ## Remaining parity work
619
+
620
+ See the [current comparison and sequence](https://github.com/uns-openhub/uns-kit/blob/master/docs/python-typescript-parity.md).
621
+ The 0.2.8 slice adds ordinary service-authority checking and asynchronous client
622
+ and database facades. The 0.2.9 slice adds managed MQTT input and HTTP ownership/
623
+ drain. Operator API and host-backed stateful transitions remain future work.
624
+ The 0.2.10 slice adds same-host Python journal handover and durable input.
625
+ TS handover transport, persistent Runtime output, retained stores and process groups
626
+ need separate versioned implementations and host acceptance. The existing
627
+ `handover` argument is currently a compatibility parameter, not an implemented
628
+ handover manager. Bounded RAM publishing and flush/drain already exist.
@@ -1,6 +1,6 @@
1
1
  [tool.poetry]
2
2
  name = "uns-kit"
3
- version = "0.2.6"
3
+ version = "0.2.11"
4
4
  description = "Lightweight Python UNS MQTT client (pub/sub + infra topics)"
5
5
  authors = ["Aljoša Vister <aljosa.vister@gmail.com>"]
6
6
  license = "MIT"
@@ -10,9 +10,11 @@ packages = [{ include = "uns_kit", from = "src" }]
10
10
  [tool.poetry.dependencies]
11
11
  python = "^3.10"
12
12
  aiomqtt = "^2.4.0"
13
+ paho-mqtt = "^2.1.0"
13
14
  click = "^8.1.7"
14
15
  infisicalsdk = { version = "^1.0.15", optional = true }
15
16
  graypy = "^2.1.0"
17
+ typing-extensions = "^4.12.2"
16
18
  fastapi = { version = "^0.116.1", optional = true }
17
19
  uvicorn = { version = "^0.35.0", optional = true }
18
20
  apscheduler = { version = "^3.11.0", optional = true }
@@ -0,0 +1,150 @@
1
+ # Python SDK migrations
2
+
3
+ ## Crossing <0.2.11 to >=0.2.11
4
+
5
+ Default API endpoint metadata now publishes retained snapshots on the Controller
6
+ registry topic `uns-infra/<package>/<version>/<process>/<instance>/api-endpoints`,
7
+ matching TypeScript. Earlier Python versions used the unrecognized `/api` suffix.
8
+ Endpoint registration events report the corrected topic too; endpoint removal
9
+ publishes the remaining snapshot on that same topic. Custom metadata consumers
10
+ must subscribe to `/api-endpoints`. Handler URLs and API authorization are unchanged.
11
+
12
+ Provision the declared parent UNS topic before exposing tree-backed API endpoints
13
+ on a fresh Controller. No ETL business-code changes are required for this fix.
14
+
15
+ ## Crossing <0.2.10 to >=0.2.10
16
+
17
+ Durable input and same-host journal hot handover are explicit opt-ins. Existing
18
+ `managed_input` RAM queues do not become persistent. Legacy `handover` arguments
19
+ do not enable `JournalHandover` or acquire TS/Controller protocol capabilities.
20
+
21
+ Provision a private local POSIX journal with stable semantic identity and bounds.
22
+ Run `DurableMqttReceiver` independently with a dedicated stable persistent-session
23
+ client ID and QoS 1 sources. Its ACK follows SQLite commit; broker persistence and
24
+ session expiry remain infrastructure responsibilities. Failed/full admission
25
+ disconnects without ACK; review storage and explicitly resume transport.
26
+
27
+ `create_journal_input()` owns one serial callback. All process-owned output must
28
+ use `publishQos: 1` and strict drain before a record is checkpointed. The new QoS
29
+ output mode makes one broker attempt and propagates uncertainty without replay.
30
+ Application DB checkpoints/idempotency must be awaited inside the handler.
31
+ Stop drains admitted application work while leaving unstarted disk records pending.
32
+ Crash/failed effects remain unconfirmed. Review the original durable operation
33
+ before an explicit persisted `reconcile(..., resolution_id=..., decision=...)`.
34
+
35
+ Prepare every proxy/API/cron before sealing `JournalHandover` contracts. Use
36
+ managed ownership, one process-owned journal source, exact launch IDs and matching
37
+ application/business resources. Only the initial owner cold-starts. A target
38
+ activates from its original prepared receipt; timeouts/repeated messages never
39
+ authorize a different writer or repeat an import. Unknown `preparing`/`applying`
40
+ operations require review. Source retirement after SIGKILL is explicitly recorded
41
+ as such and cannot masquerade as successfully executed source cleanup.
42
+
43
+ The optional state helper uses canonical Python JSON, not a TS wire-compatibility
44
+ claim. Do not advertise MQTT correlated-v2, Node process groups or host cooperative
45
+ drain receipts. No live state copying, cross-host transfer, universal exactly-once
46
+ guarantee or automatic recovery of arbitrary RAM state is added. See the source
47
+ guide `docs/python-durable-input-handover.md` for the supported contract and limits.
48
+ Managed process-owned cron now respects passive ownership, including before
49
+ initial activation; legacy processes without managed ownership keep their behavior.
50
+
51
+ ## Crossing <0.2.9 to >=0.2.9
52
+
53
+ Managed MQTT input is opt-in (`managed_input` / `managedInput`). Register one
54
+ handler, then explicitly await `start_input()` after resources and ownership are
55
+ prepared. Do not combine it with the same client's manual message iterators.
56
+ The SDK bounds admitted input, preserves failed originals and never retries a
57
+ handler automatically. Unsubscribe acknowledgement and accepted-work drain
58
+ precede output close. Overflow/uncertain work blocks a clean Stop.
59
+
60
+ HTTP requests are now tracked by default. Process/API Stop rejects new requests
61
+ and awaits accepted application work before closing resources. A disconnected
62
+ ordinary request or failed handler can leave an unknown outcome and block Stop.
63
+ Explicit `run_read_only_request()` is only for effect-free work; declare once
64
+ before the first async step/response completion. GET/POST names prove no safety.
65
+ Custom catch-all HTTP routes remain subject to their existing authorization.
66
+
67
+ Process-owned MQTT output now defaults to a bounded 1000-item queue and 32
68
+ capacity waiters, with strict drain. Explicit nonpositive queue limits preserve
69
+ legacy unbounded behavior. Strict drain latches asynchronous broker errors even
70
+ after counters reach zero; adapt cleanup code that assumed logged publish errors
71
+ were a successful flush. Standalone legacy output keeps its default behavior.
72
+
73
+ Opt-in `managed_ownership` suppresses automatic activation; call `set_active(True)`
74
+ only after preparing handlers. It is a local admission flag, not a lease or hot
75
+ handover implementation. Setting it inactive begins permanent MQTT input release;
76
+ do not reuse that released source on reactivation. HTTP gates can be used
77
+ independently. Await the same drain after timeout; never replay an unknown effect
78
+ or launch a successor just to clear a failed stop.
79
+
80
+ Continue using one application signal owner and await process Stop. This slice
81
+ does not advertise Controller cooperative-stop, persistent journals or hot
82
+ handover. See `docs/python-managed-input-http.md` for limits and acceptance.
83
+
84
+ ## Crossing <0.2.8 to >=0.2.8
85
+
86
+ Ordinary authenticated API routes now require current Controller authority for
87
+ verified machine/service claims. Configure `service_authorization_status_url`
88
+ (mapping `serviceAuthorizationStatusUrl`) or a trusted
89
+ `UNS_CONTROLLER_PUBLIC_BASE`. The status endpoint must return active protocol 1,
90
+ machine principal and `configuredAccessAuthority: 2`. Missing/old/unavailable
91
+ authority fails closed; review receiver compatibility before upgrading service
92
+ API consumers. User JWT behavior remains unchanged.
93
+
94
+ Configured UNS service credentials cannot call ordinary service APIs using path
95
+ rules: they receive 403 `service_api_permission_required`. Operator delegation
96
+ is not supported in Python ordinary endpoints. Machine path rules must be
97
+ nonempty and structurally valid. Declarations grant no live authority.
98
+
99
+ An explicitly configured token provider that returns no token no longer falls
100
+ back to interactive human login, in either sync or async clients. Synchronous
101
+ credential-bearing provider requests now reject foreign origins/redirects and
102
+ bound responses to 16 MiB. `AsyncUnsClient` provides configurable response bounds
103
+ and the same endpoint/result contracts, with bounded serialized offload.
104
+
105
+ PostgreSQL/Oracle failures now propagate without automatically replaying SQL;
106
+ their failed connection is discarded, and only a new explicit operation can
107
+ reconnect. This affects synchronous clients as well as the new async facade.
108
+ Reconcile writes after an uncertain commit instead of blindly retrying them.
109
+
110
+ `AsyncUnsClient` and `create_async_database_client()` are opt-in. Await all their
111
+ operations and close them after accepted work drains. Cancellation/asyncio
112
+ timeout stops waiting, not the underlying HTTP/SQL effect. Capacity rejection
113
+ means no operation was admitted; do not confuse it with an uncertain outcome.
114
+ Per-client workers are bounded and serialized, with SQLite connection affinity.
115
+ This release does not add transactions, streaming, pooling or hot handover.
116
+
117
+ Read the source guide `docs/python-service-access-async.md` and the bundled
118
+ README. The background declaration loader supports protocol 1 without catalog
119
+ publications and requires safe no-follow directory IO. Configured/catalog
120
+ protocols remain separate unsupported opt-ins, not implicit grants.
121
+
122
+ ## Crossing <0.2.7 to >=0.2.7
123
+
124
+ The async process owner adds optional `ProcessWork`, `ProcessLifecycleHooks`
125
+ and TS-compatible retained service metadata. Existing applications do not
126
+ automatically adopt application-work tracking, discovery declarations or signals.
127
+
128
+ `UnsProxyProcess.stop()` now makes the process inactive immediately, coalesces
129
+ concurrent calls, attempts every independent transport cleanup and reports
130
+ failures as `ProcessShutdownError` with original exceptions in `.errors`.
131
+ Adapt code relying on a particular first transport exception. Successful stop
132
+ is idempotent; reusing a stopped owner with `start()`/new proxies is rejected.
133
+ Construct a new owner after confirmed cleanup when restarting the application.
134
+
135
+ For opt-in lifecycle hooks, stop admitting new MQTT/HTTP/background work in
136
+ synchronous `on_release`, then await accepted work in `drain`. Register hooks
137
+ before inputs. Application drain precedes transport close even with `drain=False`.
138
+ A timeout does not cancel application effects: retry the same Stop to await the
139
+ same drain. A failed business effect remains unconfirmed and needs reconciliation.
140
+ Do not replay business effects or mark work successful merely to unblock cleanup.
141
+
142
+ Continue owning SIGINT/SIGTERM in the application and await `process.stop()`
143
+ from its cleanup path. This release installs no signal owner or hot handover
144
+ protocol. Existing Python `handover` parameters still do not implement TS handover.
145
+ HTTP request admission/drain and managed MQTT input are not added automatically.
146
+
147
+ `publish_service_metadata()` and its `publishServiceMetadata()` alias use TS
148
+ schemaVersion 1 on the process-scoped retained `service-metadata` topic. Use
149
+ only non-secret observations. Metadata grants no API/MQTT/database permissions
150
+ and establishes neither live health nor Controller acceptance by itself.
@@ -9,6 +9,7 @@ from .api import (
9
9
  PostEndpointOptions,
10
10
  QueryParamDef,
11
11
  UnsApiProxy,
12
+ HttpRequestDrainError,
12
13
  )
13
14
  from .core import (
14
15
  AccessTokenProvider,
@@ -24,6 +25,11 @@ from .core import (
24
25
  InfisicalResolverOptions,
25
26
  LastValueResult,
26
27
  MessageMode,
28
+ ProcessWork,
29
+ ProcessLifecycleHooks,
30
+ ProcessShutdownError,
31
+ UnsServiceMetadataInput,
32
+ build_uns_service_metadata,
27
33
  RangeQuery,
28
34
  RangeResult,
29
35
  RUNTIME_METADATA,
@@ -37,8 +43,15 @@ from .core import (
37
43
  TablePayload,
38
44
  TopicBuilder,
39
45
  UnsClient,
46
+ AsyncUnsClient,
47
+ AsyncCapacityError,
48
+ AsyncClientClosedError,
49
+ BackgroundServiceAccessDeclaration,
50
+ parse_background_service_access_declaration,
51
+ load_background_service_access_declaration,
40
52
  UnsMqttClient,
41
53
  UnsMqttProxy,
54
+ ManagedInputError,
42
55
  UnsMqttProxySync,
43
56
  UnsPacket,
44
57
  UnsParameters,
@@ -69,6 +82,8 @@ from .core import (
69
82
  from .cron import CronProxyOptions, CronSchedule, CronScheduleInput, UnsCronProxy
70
83
  from .database import (
71
84
  DatabaseClient,
85
+ AsyncDatabaseClient,
86
+ create_async_database_client,
72
87
  DatabaseConnectionConfig,
73
88
  DatabaseDialect,
74
89
  DatabaseExecuteResult,
@@ -88,6 +103,9 @@ from .database import (
88
103
  resolve_sql_file_path,
89
104
  )
90
105
  from .version import __version__
106
+ from .core.durable_journal import DurableInputJournal, JournalRecord, JournalError, JournalCapacityError, JournalOwnershipError
107
+ from .core.durable_input import DurableMqttReceiver, JournalInput
108
+ from .core.journal_handover import ApplicationHandoverState, JournalHandover, create_application_handover_contract
91
109
 
92
110
  if sys.platform.startswith("win"):
93
111
  try:
@@ -98,6 +116,8 @@ if sys.platform.startswith("win"):
98
116
  pass
99
117
 
100
118
  __all__ = [
119
+ "DurableInputJournal", "JournalRecord", "JournalError", "JournalCapacityError", "JournalOwnershipError",
120
+ "DurableMqttReceiver", "JournalInput", "ApplicationHandoverState", "JournalHandover", "create_application_handover_contract",
101
121
  "ConfigFile",
102
122
  "base_config_schema",
103
123
  "compose_config_schema",
@@ -121,13 +141,20 @@ __all__ = [
121
141
  "UnsMqttClient",
122
142
  "StatusMonitor",
123
143
  "UnsMqttProxy",
144
+ "ManagedInputError",
124
145
  "UnsMqttProxySync",
125
146
  "MessageMode",
147
+ "ProcessWork",
148
+ "ProcessLifecycleHooks",
149
+ "ProcessShutdownError",
150
+ "UnsServiceMetadataInput",
151
+ "build_uns_service_metadata",
126
152
  "UnsProxyProcess",
127
153
  "UnsProxyProcessSync",
128
154
  "UnsProcessParameters",
129
155
  "UnsParameters",
130
156
  "UnsApiProxy",
157
+ "HttpRequestDrainError",
131
158
  "ApiProxyOptions",
132
159
  "GetEndpointOptions",
133
160
  "PostEndpointOptions",
@@ -138,6 +165,12 @@ __all__ = [
138
165
  "CronSchedule",
139
166
  "CronScheduleInput",
140
167
  "UnsClient",
168
+ "AsyncUnsClient",
169
+ "AsyncCapacityError",
170
+ "AsyncClientClosedError",
171
+ "BackgroundServiceAccessDeclaration",
172
+ "parse_background_service_access_declaration",
173
+ "load_background_service_access_declaration",
141
174
  "UnsClientManager",
142
175
  "AccessTokenProvider",
143
176
  "ServiceTokenProvider",
@@ -165,6 +198,8 @@ __all__ = [
165
198
  "DatabaseDialect",
166
199
  "SqlParams",
167
200
  "DatabaseClient",
201
+ "AsyncDatabaseClient",
202
+ "create_async_database_client",
168
203
  "DatabaseQueryResult",
169
204
  "DatabaseExecuteResult",
170
205
  "DatabaseConnectionConfig",
@@ -2,6 +2,8 @@ from __future__ import annotations
2
2
 
3
3
  from .data_catalog import project_rows_for_data_catalog_schema, write_schema_rows_to_parquet
4
4
  from .proxy import ApiEventContext, ApiProxyOptions, GetEndpointOptions, PostEndpointOptions, QueryParamDef, UnsApiProxy
5
+ from .service_authority import ServiceApiAuthority, ServiceAuthorizationError, has_service_authorization_hint
6
+ from .request_lifecycle import HttpRequestDrainError
5
7
  from .event_routing import register_api_catalog, register_api_events, register_api_interactions, resolve_api_handler_path
6
8
  from .interfaces import (
7
9
  ApiInteractionDefinition,
@@ -30,6 +32,10 @@ from .interfaces import (
30
32
 
31
33
  __all__ = [
32
34
  "UnsApiProxy",
35
+ "HttpRequestDrainError",
36
+ "ServiceApiAuthority",
37
+ "ServiceAuthorizationError",
38
+ "has_service_authorization_hint",
33
39
  "ApiProxyOptions",
34
40
  "GetEndpointOptions",
35
41
  "PostEndpointOptions",