uns-kit 0.2.5__tar.gz → 0.2.10__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.5 → uns_kit-0.2.10}/PKG-INFO +126 -6
  2. {uns_kit-0.2.5 → uns_kit-0.2.10}/README.md +123 -5
  3. {uns_kit-0.2.5 → uns_kit-0.2.10}/pyproject.toml +3 -1
  4. uns_kit-0.2.10/src/uns_kit/MIGRATIONS.md +138 -0
  5. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/__init__.py +35 -0
  6. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/api/__init__.py +6 -0
  7. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/api/proxy.py +77 -16
  8. uns_kit-0.2.10/src/uns_kit/api/request_lifecycle.py +205 -0
  9. uns_kit-0.2.10/src/uns_kit/api/service_authority.py +87 -0
  10. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/cli.py +29 -26
  11. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/core/__init__.py +30 -0
  12. uns_kit-0.2.10/src/uns_kit/core/async_datahub_client.py +112 -0
  13. uns_kit-0.2.10/src/uns_kit/core/async_worker.py +86 -0
  14. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/core/client.py +25 -4
  15. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/core/datahub_client.py +8 -1
  16. uns_kit-0.2.10/src/uns_kit/core/durable_input.py +279 -0
  17. uns_kit-0.2.10/src/uns_kit/core/durable_journal.py +338 -0
  18. uns_kit-0.2.10/src/uns_kit/core/http_transport.py +76 -0
  19. uns_kit-0.2.10/src/uns_kit/core/journal_handover.py +455 -0
  20. uns_kit-0.2.10/src/uns_kit/core/lifecycle.py +30 -0
  21. uns_kit-0.2.10/src/uns_kit/core/managed_input.py +219 -0
  22. uns_kit-0.2.10/src/uns_kit/core/process_work.py +54 -0
  23. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/core/proxy.py +18 -0
  24. uns_kit-0.2.10/src/uns_kit/core/proxy_process.py +600 -0
  25. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/core/proxy_process_sync.py +6 -1
  26. uns_kit-0.2.10/src/uns_kit/core/service_access.py +104 -0
  27. uns_kit-0.2.10/src/uns_kit/core/service_metadata.py +95 -0
  28. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/core/topic_builder.py +3 -0
  29. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/core/uns_mqtt_proxy.py +244 -14
  30. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/cron/proxy.py +5 -2
  31. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/database/__init__.py +3 -0
  32. uns_kit-0.2.10/src/uns_kit/database/async_client.py +78 -0
  33. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/database/client.py +6 -29
  34. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/service_bundle.py +7 -0
  35. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/templates/default/README.md +19 -9
  36. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/templates/default/package.json +1 -1
  37. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/templates/vscode/settings.json +2 -1
  38. uns_kit-0.2.5/src/uns_kit/core/proxy_process.py +0 -345
  39. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/api/data_catalog.py +0 -0
  40. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/api/event_routing.py +0 -0
  41. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/api/interfaces.py +0 -0
  42. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/core/auth_client.py +0 -0
  43. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/core/config_file.py +0 -0
  44. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/core/config_schema.py +0 -0
  45. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/core/events.py +0 -0
  46. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/core/logger.py +0 -0
  47. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/core/packet.py +0 -0
  48. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/core/runtime_metadata.py +0 -0
  49. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/core/runtime_service_registration.py +0 -0
  50. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/core/secret_resolver.py +0 -0
  51. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/core/secure_store.py +0 -0
  52. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/core/service_token_provider.py +0 -0
  53. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/core/state.py +0 -0
  54. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/core/status_monitor.py +0 -0
  55. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/core/topic_matcher.py +0 -0
  56. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/core/uns_path.py +0 -0
  57. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/cron/__init__.py +0 -0
  58. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/database/params.py +0 -0
  59. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/database/schema.py +0 -0
  60. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/database/sql.py +0 -0
  61. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/database/types.py +0 -0
  62. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/templates/api/src/api_routes.py +0 -0
  63. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/templates/api/src/main.py +0 -0
  64. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/templates/azure-pipelines.yml +0 -0
  65. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/templates/cron/src/cron_example.py +0 -0
  66. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/templates/data-offer/src/api_routes.py +0 -0
  67. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/templates/data-offer/src/data_offers/__init__.py +0 -0
  68. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/templates/data-offer/src/data_offers/demo_coils.py +0 -0
  69. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/templates/data-offer/src/data_offers/demo_export.py +0 -0
  70. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/templates/data-offer/src/data_offers/sql/demo_coils.sql +0 -0
  71. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/templates/data-offer/src/data_offers/sql/demo_export.sql +0 -0
  72. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/templates/data-offer/src/main.py +0 -0
  73. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/templates/default/.gitignore +0 -0
  74. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/templates/default/pyproject.toml +0 -0
  75. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/templates/default/runtime.json +0 -0
  76. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/templates/default/src/config/project_config_extension.example.py +0 -0
  77. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/templates/default/src/config/project_config_extension.py +0 -0
  78. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/templates/default/src/main.py +0 -0
  79. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/templates/vscode/extensions.json +0 -0
  80. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/templates/vscode/launch.json +0 -0
  81. {uns_kit-0.2.5 → uns_kit-0.2.10}/src/uns_kit/templates/workspace/workspace.json +0 -0
  82. {uns_kit-0.2.5 → uns_kit-0.2.10}/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.5
3
+ Version: 0.2.10
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,118 @@ 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
+ ## Durable input and same-host hot handover (0.2.10)
45
+
46
+ Opt-in `DurableInputJournal`, independent `DurableMqttReceiver` and `JournalInput`
47
+ commit QoS 1 input before ACK and checkpoint only after handlers and output flush.
48
+ Capacity pauses admission without pruning pending input. Unknown effects survive
49
+ restart for explicit reconciliation instead of automatic business replay.
50
+
51
+ `JournalHandover` switches one shared local journal between exact Python owners,
52
+ drains HTTP/application work, validates/restores application and output state once,
53
+ and persists operation phases. It requires private local POSIX storage and strict
54
+ QoS 1 output. Existing RAM-only inputs and legacy handover arguments are unchanged.
55
+
56
+ Read [the guide](https://github.com/uns-openhub/uns-kit/blob/master/docs/python-durable-input-handover.md) and bundled 0.2.10
57
+ migration entry. This is Python journal protocol 1; TS correlated-v2, Controller
58
+ process-group authorization, cross-host transfer and online backups remain separate.
59
+
60
+ ## Managed MQTT input and HTTP drain (0.2.9)
61
+
62
+ Managed MQTT input has one explicit async handler, bounded count/bytes, subscription
63
+ readiness and unsubscribe-before-drain. Enable it with `managedInput: true` in
64
+ `UnsParameters`, register `set_input_handler()` and await `start_input()`.
65
+ Failed input remains available for review and is never replayed automatically.
66
+
67
+ HTTP requests now remain owned through application completion, including after
68
+ disconnect. Ownership gates return retryable 503 responses on passive owners.
69
+ `drain_requests()`/Stop waits for accepted work; unknown effects block clean Stop.
70
+ Use `run_read_only_request(event, factory)` only for explicitly effect-free work.
71
+
72
+ Process Stop drains managed input and HTTP before application cleanup/output
73
+ close. Owned outputs have bounded capacity waiting and strict publish drain.
74
+ Read the bundled 0.2.9 migration entry before upgrading existing cleanup flows.
75
+ The [guide and tested examples](https://github.com/uns-openhub/uns-kit/blob/master/docs/python-managed-input-http.md)
76
+ describe local ownership, real broker/HTTP acceptance and remaining limits.
77
+
78
+ ## Service authority and async clients (0.2.8)
79
+
80
+ `AsyncUnsClient` and `create_async_database_client()` reuse the existing API/SQL
81
+ contracts through bounded worker threads, so blocking IO stays off asyncio.
82
+ The service token is reread for every authorized request. Each client serializes
83
+ operations and supports `async with` or explicit awaited `close()`.
84
+
85
+ ```python
86
+ from uns_kit import AsyncUnsClient, create_async_database_client
87
+
88
+ async with AsyncUnsClient(controller_base) as client:
89
+ history = await client.history("example/site/line/equipment/main/temperature", limit=100)
90
+
91
+ async with create_async_database_client(resolved_database_config) as database:
92
+ rows = await database.query_file("queries/read-window.sql", {"fromTs": from_time})
93
+ ```
94
+
95
+ The default async credential source is `ServiceTokenProvider`; missing service
96
+ credentials never cause implicit human login. Cancellation stops waiting while
97
+ accepted IO remains owned; close waits for it. Do not retry a possibly committed
98
+ POST/SQL operation merely because its caller timed out.
99
+
100
+ Authenticated Python API receivers now require a fresh Controller token-status
101
+ check for verified service/machine claims. Configure the trusted
102
+ `service_authorization_status_url` option or `UNS_CONTROLLER_PUBLIC_BASE`, and
103
+ require `configuredAccessAuthority: 2`. Older/unavailable status endpoints fail
104
+ closed. Configured UNS grants and unsupported Operator delegations cannot call
105
+ ordinary service APIs. Existing ordinary user JWT semantics are preserved.
106
+
107
+ Read the bundled `uns_kit/MIGRATIONS.md` before updating receivers or relying on
108
+ automatic SQL recovery: PostgreSQL/Oracle no longer replay failed operations.
109
+ See the [full guide and limits](https://github.com/uns-openhub/uns-kit/blob/master/docs/python-service-access-async.md)
110
+ and [two reference readers](https://github.com/uns-openhub/uns-kit/tree/master/examples/python-service-access).
111
+
112
+ ## Runtime and discovery parity (0.2.7)
113
+
114
+ Python now provides `ProcessWork`, opt-in `ProcessLifecycleHooks` and the same
115
+ retained service-metadata wire contract as TS. Read the bundled
116
+ `uns_kit/MIGRATIONS.md` when crossing 0.2.7, especially if you reuse process
117
+ owners after stopping or catch specific cleanup exceptions. The
118
+ [parity matrix and supported limits](https://github.com/uns-openhub/uns-kit/blob/master/docs/python-typescript-parity.md)
119
+ distinguish implemented mechanisms from planned TS capabilities.
120
+
121
+ ```python
122
+ from uns_kit import ProcessWork, ProcessLifecycleHooks
123
+
124
+ # After constructing your UnsProxyProcess, before starting application inputs:
125
+ accepted = ProcessWork(process.is_active)
126
+
127
+ def release_inputs():
128
+ # Also close your application's MQTT/HTTP input admission here.
129
+ accepted.pause()
130
+
131
+ process.register_lifecycle_participant(ProcessLifecycleHooks(
132
+ on_release=release_inputs,
133
+ drain=accepted.drain,
134
+ ))
135
+
136
+ # Background polling: await accepted.run(poll_and_publish)
137
+ # Already accepted transport input: await accepted.track(handle_message(message))
138
+ # These helpers do not limit concurrency; keep admission bounded separately.
139
+
140
+ await process.publish_service_metadata({
141
+ "serviceId": "example-processor",
142
+ "kind": "service",
143
+ "capabilities": ["telemetry-processing"],
144
+ })
145
+
146
+ # From the application's existing signal/finally cleanup path:
147
+ await process.stop() # also available as await process.shutdown()
148
+ ```
149
+
150
+ Stop first runs release hooks, then awaits accepted application work before
151
+ closing transports. Timeout does not cancel that work: another Stop awaits the
152
+ same drain. Drain failures block a clean stop. The application continues to own
153
+ signals, MQTT/HTTP admission and business resource cleanup. This does not add a
154
+ durable job queue, HTTP ownership transfer or hot handover.
155
+
42
156
  ## 0.2.0 table migration
43
157
 
44
158
  `UnsPacket.table()` now emits MQTT packet version `2.0.0` and named object
@@ -529,9 +643,15 @@ When created inside this monorepo, `pyproject.toml` is automatically set to use
529
643
  - Packet shape mirrors the TypeScript core: `{"version":"1.3.0","message":{"data":{...}},"sequenceId":0}`.
530
644
  - Windows: the library sets `WindowsSelectorEventLoopPolicy()` to avoid `add_reader/add_writer` `NotImplementedError`.
531
645
 
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.
646
+ ## Remaining parity work
647
+
648
+ See the [current comparison and sequence](https://github.com/uns-openhub/uns-kit/blob/master/docs/python-typescript-parity.md).
649
+ The 0.2.8 slice adds ordinary service-authority checking and asynchronous client
650
+ and database facades. The 0.2.9 slice adds managed MQTT input and HTTP ownership/
651
+ drain. Operator API and host-backed stateful transitions remain future work.
652
+ The 0.2.10 slice adds same-host Python journal handover and durable input.
653
+ TS handover transport, persistent Runtime output, retained stores and process groups
654
+ need separate versioned implementations and host acceptance. The existing
655
+ `handover` argument is currently a compatibility parameter, not an implemented
656
+ handover manager. Bounded RAM publishing and flush/drain already exist.
537
657
 
@@ -6,6 +6,118 @@ 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
+ ## Durable input and same-host hot handover (0.2.10)
10
+
11
+ Opt-in `DurableInputJournal`, independent `DurableMqttReceiver` and `JournalInput`
12
+ commit QoS 1 input before ACK and checkpoint only after handlers and output flush.
13
+ Capacity pauses admission without pruning pending input. Unknown effects survive
14
+ restart for explicit reconciliation instead of automatic business replay.
15
+
16
+ `JournalHandover` switches one shared local journal between exact Python owners,
17
+ drains HTTP/application work, validates/restores application and output state once,
18
+ and persists operation phases. It requires private local POSIX storage and strict
19
+ QoS 1 output. Existing RAM-only inputs and legacy handover arguments are unchanged.
20
+
21
+ Read [the guide](https://github.com/uns-openhub/uns-kit/blob/master/docs/python-durable-input-handover.md) and bundled 0.2.10
22
+ migration entry. This is Python journal protocol 1; TS correlated-v2, Controller
23
+ process-group authorization, cross-host transfer and online backups remain separate.
24
+
25
+ ## Managed MQTT input and HTTP drain (0.2.9)
26
+
27
+ Managed MQTT input has one explicit async handler, bounded count/bytes, subscription
28
+ readiness and unsubscribe-before-drain. Enable it with `managedInput: true` in
29
+ `UnsParameters`, register `set_input_handler()` and await `start_input()`.
30
+ Failed input remains available for review and is never replayed automatically.
31
+
32
+ HTTP requests now remain owned through application completion, including after
33
+ disconnect. Ownership gates return retryable 503 responses on passive owners.
34
+ `drain_requests()`/Stop waits for accepted work; unknown effects block clean Stop.
35
+ Use `run_read_only_request(event, factory)` only for explicitly effect-free work.
36
+
37
+ Process Stop drains managed input and HTTP before application cleanup/output
38
+ close. Owned outputs have bounded capacity waiting and strict publish drain.
39
+ Read the bundled 0.2.9 migration entry before upgrading existing cleanup flows.
40
+ The [guide and tested examples](https://github.com/uns-openhub/uns-kit/blob/master/docs/python-managed-input-http.md)
41
+ describe local ownership, real broker/HTTP acceptance and remaining limits.
42
+
43
+ ## Service authority and async clients (0.2.8)
44
+
45
+ `AsyncUnsClient` and `create_async_database_client()` reuse the existing API/SQL
46
+ contracts through bounded worker threads, so blocking IO stays off asyncio.
47
+ The service token is reread for every authorized request. Each client serializes
48
+ operations and supports `async with` or explicit awaited `close()`.
49
+
50
+ ```python
51
+ from uns_kit import AsyncUnsClient, create_async_database_client
52
+
53
+ async with AsyncUnsClient(controller_base) as client:
54
+ history = await client.history("example/site/line/equipment/main/temperature", limit=100)
55
+
56
+ async with create_async_database_client(resolved_database_config) as database:
57
+ rows = await database.query_file("queries/read-window.sql", {"fromTs": from_time})
58
+ ```
59
+
60
+ The default async credential source is `ServiceTokenProvider`; missing service
61
+ credentials never cause implicit human login. Cancellation stops waiting while
62
+ accepted IO remains owned; close waits for it. Do not retry a possibly committed
63
+ POST/SQL operation merely because its caller timed out.
64
+
65
+ Authenticated Python API receivers now require a fresh Controller token-status
66
+ check for verified service/machine claims. Configure the trusted
67
+ `service_authorization_status_url` option or `UNS_CONTROLLER_PUBLIC_BASE`, and
68
+ require `configuredAccessAuthority: 2`. Older/unavailable status endpoints fail
69
+ closed. Configured UNS grants and unsupported Operator delegations cannot call
70
+ ordinary service APIs. Existing ordinary user JWT semantics are preserved.
71
+
72
+ Read the bundled `uns_kit/MIGRATIONS.md` before updating receivers or relying on
73
+ automatic SQL recovery: PostgreSQL/Oracle no longer replay failed operations.
74
+ See the [full guide and limits](https://github.com/uns-openhub/uns-kit/blob/master/docs/python-service-access-async.md)
75
+ and [two reference readers](https://github.com/uns-openhub/uns-kit/tree/master/examples/python-service-access).
76
+
77
+ ## Runtime and discovery parity (0.2.7)
78
+
79
+ Python now provides `ProcessWork`, opt-in `ProcessLifecycleHooks` and the same
80
+ retained service-metadata wire contract as TS. Read the bundled
81
+ `uns_kit/MIGRATIONS.md` when crossing 0.2.7, especially if you reuse process
82
+ owners after stopping or catch specific cleanup exceptions. The
83
+ [parity matrix and supported limits](https://github.com/uns-openhub/uns-kit/blob/master/docs/python-typescript-parity.md)
84
+ distinguish implemented mechanisms from planned TS capabilities.
85
+
86
+ ```python
87
+ from uns_kit import ProcessWork, ProcessLifecycleHooks
88
+
89
+ # After constructing your UnsProxyProcess, before starting application inputs:
90
+ accepted = ProcessWork(process.is_active)
91
+
92
+ def release_inputs():
93
+ # Also close your application's MQTT/HTTP input admission here.
94
+ accepted.pause()
95
+
96
+ process.register_lifecycle_participant(ProcessLifecycleHooks(
97
+ on_release=release_inputs,
98
+ drain=accepted.drain,
99
+ ))
100
+
101
+ # Background polling: await accepted.run(poll_and_publish)
102
+ # Already accepted transport input: await accepted.track(handle_message(message))
103
+ # These helpers do not limit concurrency; keep admission bounded separately.
104
+
105
+ await process.publish_service_metadata({
106
+ "serviceId": "example-processor",
107
+ "kind": "service",
108
+ "capabilities": ["telemetry-processing"],
109
+ })
110
+
111
+ # From the application's existing signal/finally cleanup path:
112
+ await process.stop() # also available as await process.shutdown()
113
+ ```
114
+
115
+ Stop first runs release hooks, then awaits accepted application work before
116
+ closing transports. Timeout does not cancel that work: another Stop awaits the
117
+ same drain. Drain failures block a clean stop. The application continues to own
118
+ signals, MQTT/HTTP admission and business resource cleanup. This does not add a
119
+ durable job queue, HTTP ownership transfer or hot handover.
120
+
9
121
  ## 0.2.0 table migration
10
122
 
11
123
  `UnsPacket.table()` now emits MQTT packet version `2.0.0` and named object
@@ -496,8 +608,14 @@ When created inside this monorepo, `pyproject.toml` is automatically set to use
496
608
  - Packet shape mirrors the TypeScript core: `{"version":"1.3.0","message":{"data":{...}},"sequenceId":0}`.
497
609
  - Windows: the library sets `WindowsSelectorEventLoopPolicy()` to avoid `add_reader/add_writer` `NotImplementedError`.
498
610
 
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.
611
+ ## Remaining parity work
612
+
613
+ See the [current comparison and sequence](https://github.com/uns-openhub/uns-kit/blob/master/docs/python-typescript-parity.md).
614
+ The 0.2.8 slice adds ordinary service-authority checking and asynchronous client
615
+ and database facades. The 0.2.9 slice adds managed MQTT input and HTTP ownership/
616
+ drain. Operator API and host-backed stateful transitions remain future work.
617
+ The 0.2.10 slice adds same-host Python journal handover and durable input.
618
+ TS handover transport, persistent Runtime output, retained stores and process groups
619
+ need separate versioned implementations and host acceptance. The existing
620
+ `handover` argument is currently a compatibility parameter, not an implemented
621
+ 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.5"
3
+ version = "0.2.10"
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,138 @@
1
+ # Python SDK migrations
2
+
3
+ ## Crossing <0.2.10 to >=0.2.10
4
+
5
+ Durable input and same-host journal hot handover are explicit opt-ins. Existing
6
+ `managed_input` RAM queues do not become persistent. Legacy `handover` arguments
7
+ do not enable `JournalHandover` or acquire TS/Controller protocol capabilities.
8
+
9
+ Provision a private local POSIX journal with stable semantic identity and bounds.
10
+ Run `DurableMqttReceiver` independently with a dedicated stable persistent-session
11
+ client ID and QoS 1 sources. Its ACK follows SQLite commit; broker persistence and
12
+ session expiry remain infrastructure responsibilities. Failed/full admission
13
+ disconnects without ACK; review storage and explicitly resume transport.
14
+
15
+ `create_journal_input()` owns one serial callback. All process-owned output must
16
+ use `publishQos: 1` and strict drain before a record is checkpointed. The new QoS
17
+ output mode makes one broker attempt and propagates uncertainty without replay.
18
+ Application DB checkpoints/idempotency must be awaited inside the handler.
19
+ Stop drains admitted application work while leaving unstarted disk records pending.
20
+ Crash/failed effects remain unconfirmed. Review the original durable operation
21
+ before an explicit persisted `reconcile(..., resolution_id=..., decision=...)`.
22
+
23
+ Prepare every proxy/API/cron before sealing `JournalHandover` contracts. Use
24
+ managed ownership, one process-owned journal source, exact launch IDs and matching
25
+ application/business resources. Only the initial owner cold-starts. A target
26
+ activates from its original prepared receipt; timeouts/repeated messages never
27
+ authorize a different writer or repeat an import. Unknown `preparing`/`applying`
28
+ operations require review. Source retirement after SIGKILL is explicitly recorded
29
+ as such and cannot masquerade as successfully executed source cleanup.
30
+
31
+ The optional state helper uses canonical Python JSON, not a TS wire-compatibility
32
+ claim. Do not advertise MQTT correlated-v2, Node process groups or host cooperative
33
+ drain receipts. No live state copying, cross-host transfer, universal exactly-once
34
+ guarantee or automatic recovery of arbitrary RAM state is added. See the source
35
+ guide `docs/python-durable-input-handover.md` for the supported contract and limits.
36
+ Managed process-owned cron now respects passive ownership, including before
37
+ initial activation; legacy processes without managed ownership keep their behavior.
38
+
39
+ ## Crossing <0.2.9 to >=0.2.9
40
+
41
+ Managed MQTT input is opt-in (`managed_input` / `managedInput`). Register one
42
+ handler, then explicitly await `start_input()` after resources and ownership are
43
+ prepared. Do not combine it with the same client's manual message iterators.
44
+ The SDK bounds admitted input, preserves failed originals and never retries a
45
+ handler automatically. Unsubscribe acknowledgement and accepted-work drain
46
+ precede output close. Overflow/uncertain work blocks a clean Stop.
47
+
48
+ HTTP requests are now tracked by default. Process/API Stop rejects new requests
49
+ and awaits accepted application work before closing resources. A disconnected
50
+ ordinary request or failed handler can leave an unknown outcome and block Stop.
51
+ Explicit `run_read_only_request()` is only for effect-free work; declare once
52
+ before the first async step/response completion. GET/POST names prove no safety.
53
+ Custom catch-all HTTP routes remain subject to their existing authorization.
54
+
55
+ Process-owned MQTT output now defaults to a bounded 1000-item queue and 32
56
+ capacity waiters, with strict drain. Explicit nonpositive queue limits preserve
57
+ legacy unbounded behavior. Strict drain latches asynchronous broker errors even
58
+ after counters reach zero; adapt cleanup code that assumed logged publish errors
59
+ were a successful flush. Standalone legacy output keeps its default behavior.
60
+
61
+ Opt-in `managed_ownership` suppresses automatic activation; call `set_active(True)`
62
+ only after preparing handlers. It is a local admission flag, not a lease or hot
63
+ handover implementation. Setting it inactive begins permanent MQTT input release;
64
+ do not reuse that released source on reactivation. HTTP gates can be used
65
+ independently. Await the same drain after timeout; never replay an unknown effect
66
+ or launch a successor just to clear a failed stop.
67
+
68
+ Continue using one application signal owner and await process Stop. This slice
69
+ does not advertise Controller cooperative-stop, persistent journals or hot
70
+ handover. See `docs/python-managed-input-http.md` for limits and acceptance.
71
+
72
+ ## Crossing <0.2.8 to >=0.2.8
73
+
74
+ Ordinary authenticated API routes now require current Controller authority for
75
+ verified machine/service claims. Configure `service_authorization_status_url`
76
+ (mapping `serviceAuthorizationStatusUrl`) or a trusted
77
+ `UNS_CONTROLLER_PUBLIC_BASE`. The status endpoint must return active protocol 1,
78
+ machine principal and `configuredAccessAuthority: 2`. Missing/old/unavailable
79
+ authority fails closed; review receiver compatibility before upgrading service
80
+ API consumers. User JWT behavior remains unchanged.
81
+
82
+ Configured UNS service credentials cannot call ordinary service APIs using path
83
+ rules: they receive 403 `service_api_permission_required`. Operator delegation
84
+ is not supported in Python ordinary endpoints. Machine path rules must be
85
+ nonempty and structurally valid. Declarations grant no live authority.
86
+
87
+ An explicitly configured token provider that returns no token no longer falls
88
+ back to interactive human login, in either sync or async clients. Synchronous
89
+ credential-bearing provider requests now reject foreign origins/redirects and
90
+ bound responses to 16 MiB. `AsyncUnsClient` provides configurable response bounds
91
+ and the same endpoint/result contracts, with bounded serialized offload.
92
+
93
+ PostgreSQL/Oracle failures now propagate without automatically replaying SQL;
94
+ their failed connection is discarded, and only a new explicit operation can
95
+ reconnect. This affects synchronous clients as well as the new async facade.
96
+ Reconcile writes after an uncertain commit instead of blindly retrying them.
97
+
98
+ `AsyncUnsClient` and `create_async_database_client()` are opt-in. Await all their
99
+ operations and close them after accepted work drains. Cancellation/asyncio
100
+ timeout stops waiting, not the underlying HTTP/SQL effect. Capacity rejection
101
+ means no operation was admitted; do not confuse it with an uncertain outcome.
102
+ Per-client workers are bounded and serialized, with SQLite connection affinity.
103
+ This release does not add transactions, streaming, pooling or hot handover.
104
+
105
+ Read the source guide `docs/python-service-access-async.md` and the bundled
106
+ README. The background declaration loader supports protocol 1 without catalog
107
+ publications and requires safe no-follow directory IO. Configured/catalog
108
+ protocols remain separate unsupported opt-ins, not implicit grants.
109
+
110
+ ## Crossing <0.2.7 to >=0.2.7
111
+
112
+ The async process owner adds optional `ProcessWork`, `ProcessLifecycleHooks`
113
+ and TS-compatible retained service metadata. Existing applications do not
114
+ automatically adopt application-work tracking, discovery declarations or signals.
115
+
116
+ `UnsProxyProcess.stop()` now makes the process inactive immediately, coalesces
117
+ concurrent calls, attempts every independent transport cleanup and reports
118
+ failures as `ProcessShutdownError` with original exceptions in `.errors`.
119
+ Adapt code relying on a particular first transport exception. Successful stop
120
+ is idempotent; reusing a stopped owner with `start()`/new proxies is rejected.
121
+ Construct a new owner after confirmed cleanup when restarting the application.
122
+
123
+ For opt-in lifecycle hooks, stop admitting new MQTT/HTTP/background work in
124
+ synchronous `on_release`, then await accepted work in `drain`. Register hooks
125
+ before inputs. Application drain precedes transport close even with `drain=False`.
126
+ A timeout does not cancel application effects: retry the same Stop to await the
127
+ same drain. A failed business effect remains unconfirmed and needs reconciliation.
128
+ Do not replay business effects or mark work successful merely to unblock cleanup.
129
+
130
+ Continue owning SIGINT/SIGTERM in the application and await `process.stop()`
131
+ from its cleanup path. This release installs no signal owner or hot handover
132
+ protocol. Existing Python `handover` parameters still do not implement TS handover.
133
+ HTTP request admission/drain and managed MQTT input are not added automatically.
134
+
135
+ `publish_service_metadata()` and its `publishServiceMetadata()` alias use TS
136
+ schemaVersion 1 on the process-scoped retained `service-metadata` topic. Use
137
+ only non-secret observations. Metadata grants no API/MQTT/database permissions
138
+ 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",