requence 0.8.1.dev55__tar.gz → 0.8.1.dev62__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 (78) hide show
  1. {requence-0.8.1.dev55/requence.egg-info → requence-0.8.1.dev62}/PKG-INFO +255 -17
  2. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/README.md +254 -15
  3. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/pyproject.toml +1 -2
  4. requence-0.8.1.dev62/requence/context.py +103 -0
  5. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/exceptions.py +16 -0
  6. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/files/handlers/claim_check_handler.py +4 -0
  7. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/files/handlers/context.py +7 -0
  8. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/internal_types.py +7 -1
  9. requence-0.8.1.dev62/requence/logger.py +118 -0
  10. requence-0.8.1.dev62/requence/service/__init__.py +1705 -0
  11. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/service/boundary.py +36 -4
  12. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/service/cli.py +13 -23
  13. requence-0.8.1.dev62/requence/service/surface_handler.py +53 -0
  14. requence-0.8.1.dev62/requence/service/transformer.py +44 -0
  15. requence-0.8.1.dev62/requence/service/ui.py +152 -0
  16. requence-0.8.1.dev62/requence/service/ui_watch.py +281 -0
  17. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/task/cli.py +7 -9
  18. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/task/task.py +2 -3
  19. requence-0.8.1.dev62/requence/wire.py +287 -0
  20. {requence-0.8.1.dev55 → requence-0.8.1.dev62/requence.egg-info}/PKG-INFO +255 -17
  21. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence.egg-info/SOURCES.txt +5 -0
  22. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence.egg-info/requires.txt +0 -1
  23. requence-0.8.1.dev62/tests/test_logger.py +152 -0
  24. requence-0.8.1.dev55/requence/context.py +0 -62
  25. requence-0.8.1.dev55/requence/service/__init__.py +0 -927
  26. requence-0.8.1.dev55/requence/service/transformer.py +0 -21
  27. requence-0.8.1.dev55/requence/wire.py +0 -128
  28. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/MANIFEST.in +0 -0
  29. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/__init__.py +0 -0
  30. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/callbacks/__init__.py +0 -0
  31. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/callbacks/context.py +0 -0
  32. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/callbacks/handler.py +0 -0
  33. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/client_properties.py +0 -0
  34. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/files/__init__.py +0 -0
  35. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/files/errors.py +0 -0
  36. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/files/handlers/__init__.py +0 -0
  37. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/files/handlers/file_handler.py +0 -0
  38. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/files/handlers/stream_handler.py +0 -0
  39. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/files/pending_uploads.py +0 -0
  40. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/files/requence_file.py +0 -0
  41. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/files/requence_stream.py +0 -0
  42. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/files/sanitize_log_data.py +0 -0
  43. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/files/stream_framing.py +0 -0
  44. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/files/transport.py +0 -0
  45. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/obfuscase.py +0 -0
  46. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/py.typed +0 -0
  47. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/reachable.py +0 -0
  48. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/requence_callback.py +0 -0
  49. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/requence_file.py +0 -0
  50. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/requence_stream.py +0 -0
  51. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/service/types.py +0 -0
  52. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/task/__init__.py +0 -0
  53. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/task/abort_task.py +0 -0
  54. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/task/ack_task.py +0 -0
  55. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/task/get_task.py +0 -0
  56. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/task/ingress.py +0 -0
  57. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/task/protect_task.py +0 -0
  58. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/task/task_watcher.py +0 -0
  59. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/task/types.py +0 -0
  60. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/task/updates.py +0 -0
  61. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/task/utils.py +0 -0
  62. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/transformer/__init__.py +0 -0
  63. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/transformer/context.py +0 -0
  64. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/transformer/errors.py +0 -0
  65. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/transformer/guards.py +0 -0
  66. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/transformer/message_handler.py +0 -0
  67. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/transformer/transform.py +0 -0
  68. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/transformer/value_handler.py +0 -0
  69. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/transformer/walk.py +0 -0
  70. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/utils.py +0 -0
  71. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence/wire_codec.py +0 -0
  72. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence.egg-info/dependency_links.txt +0 -0
  73. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence.egg-info/entry_points.txt +0 -0
  74. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/requence.egg-info/top_level.txt +0 -0
  75. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/setup.cfg +0 -0
  76. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/tests/test_client_properties.py +0 -0
  77. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/tests/test_wire.py +0 -0
  78. {requence-0.8.1.dev55 → requence-0.8.1.dev62}/tests/test_wire_codec.py +0 -0
@@ -1,13 +1,12 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: requence
3
- Version: 0.8.1.dev55
3
+ Version: 0.8.1.dev62
4
4
  Summary: Requence Service
5
5
  Author: Torsten Blindert
6
6
  Requires-Python: >=3.12
7
7
  Description-Content-Type: text/markdown
8
8
  Requires-Dist: pika>=1.3.2
9
9
  Requires-Dist: requests>=2.32.2
10
- Requires-Dist: colorama>=0.4.6
11
10
  Requires-Dist: sseclient-py>=1.8.0
12
11
  Requires-Dist: msgpack>=1.0.5
13
12
 
@@ -112,30 +111,49 @@ Service(
112
111
 
113
112
  The dev token is resolved in the same order as the access token — `dev_token` argument → `REQUENCE_SERVICE_DEV_TOKEN` / `REQUENCE_DEV_TOKEN` env var → `requence.service_dev_token` / `requence.dev_token` in `pyproject.toml`.
114
113
 
115
- ### Closing the service
114
+ ### Two ways to start — and why it matters
116
115
 
117
- `Service.__init__` blocks the current thread (it calls `channel.start_consuming()`). To stop consuming from another thread, call `close()`:
116
+ `Service(...)` configures the service and then **consumes on the calling thread**, so it never returns while the service is up:
117
+
118
+ ```python
119
+ from requence.service import Service
120
+
121
+ Service("1.0.0", lambda ctx: ctx.input) # blocks here forever
122
+ ```
123
+
124
+ That is the right shape when the service is the whole program. But it means there is **no instance to call methods on** — so `act()` and `close()`, which are both methods, are out of reach. Use `Service.start(...)` when you need either. It is the same configuration with the consume loop on a thread of its own, and it **returns the instance** once connected:
118
125
 
119
126
  ```python
120
127
  import threading
121
128
  from requence.service import Service
122
129
 
123
- service = None
130
+ service = Service.start("1.0.0", lambda ctx: ctx.input)
131
+ # ...connected; `service` is usable here
124
132
 
125
- def handler(ctx):
126
- return ctx.input
133
+ threading.Event().wait() # keep the main thread alive; see below
134
+ ```
127
135
 
128
- def run():
129
- global service
130
- service = Service("1.0.0", handler)
136
+ | | `Service(...)` | `Service.start(...)` |
137
+ |---|---|---|
138
+ | Returns | never (while up) | once connected |
139
+ | `act()` / `close()` | unreachable | usable |
140
+ | Bad credentials | raises | raises |
141
+ | Consume thread | the caller's | a daemon thread |
131
142
 
132
- thread = threading.Thread(target=run)
133
- thread.start()
143
+ `start(..., timeout=30.0)` bounds only the **first** connect; every drop after it reconnects in the background as always. A first connect that never lands raises `TimeoutError` and stops retrying, so you never get back an instance you cannot use.
134
144
 
135
- # Later, from another thread:
145
+ Its consume thread is a **daemon**, so it never holds the process open. If the service is the whole program, keep the main thread alive yourself — a `threading.Event().wait()`, a web server, a REPL — or just use the blocking `Service(...)`.
146
+
147
+ ### Closing the service
148
+
149
+ ```python
150
+ service = Service.start("1.0.0", handler)
151
+ # ...later, from anywhere:
136
152
  service.close()
137
153
  ```
138
154
 
155
+ `close()` stops consuming and stops reconnecting. It is safe to call from any thread: the channel work is marshalled onto the connection's own thread.
156
+
139
157
  ---
140
158
 
141
159
  ## Context API
@@ -253,18 +271,18 @@ The generator is stopped automatically when `ctx.terminated` is set. Any yielded
253
271
 
254
272
  ## Deferred Delivery via `service.act()`
255
273
 
256
- After deferring a message with `ctx.defer()`, deliver the result later — even from a different process — using the `act()` method on the `Service` instance:
274
+ After deferring a message with `ctx.defer()`, deliver the result later — even from a different process — using the `act()` method on the `Service` instance.
275
+
276
+ **Start the service with `Service.start(...)`**, not `Service(...)`: `act()` is a method, and the blocking constructor never returns the object to call it on.
257
277
 
258
278
  ```python
259
279
  from requence.service import Service
260
280
 
261
- service = None
262
-
263
281
  def handler(ctx):
264
282
  message_key = ctx.defer()
265
283
  save_to_db(ctx.task_id, message_key)
266
284
 
267
- service = Service("1.0.0", handler) # blocks
285
+ service = Service.start("1.0.0", handler) # returns
268
286
  ```
269
287
 
270
288
  ```python
@@ -279,6 +297,8 @@ def actor(api):
279
297
  service.act(message_key, actor)
280
298
  ```
281
299
 
300
+ `act()` may be called from any thread — a web request handler, a scheduler, a durable surface handler. It publishes through the connection's own thread and does not return until everything it published has actually gone out, so a script that calls `act()` and then exits does not lose the answer.
301
+
282
302
  The `actor` callable receives an `api` dict with three keys:
283
303
 
284
304
  | Key | Description |
@@ -286,11 +306,229 @@ The `actor` callable receives an `api` dict with three keys:
286
306
  | `api["send"](data)` | Send data to the default output |
287
307
  | `api["send_to_output"](name, data)` | Send data to a named output |
288
308
  | `api["abort"](error)` | Abort the deferred message with an error string or exception |
309
+ | `api["render"](ui, props, surface_id=…)` | Draw or redraw a surface on the deferred node — see [Surfaces](#surfaces--a-ui-of-your-own-on-the-node) |
289
310
 
290
311
  The actor can also return a value or a generator directly, which behaves like calling `api["send"]()` for each value.
291
312
 
292
313
  ---
293
314
 
315
+ ## Surfaces — a UI of your own on the node
316
+
317
+ A service can ship its own UI component and have Requence render it **on the
318
+ publishing node** in the task canvas. There is no UI protocol: the contract is
319
+ **props**, and a callable inside them arrives in the component as an invokable
320
+ function.
321
+
322
+ The design authority is
323
+ [`knowledge/service-ui-surfaces.md`](../knowledge/service-ui-surfaces.md); this
324
+ section is the Python API. The TypeScript SDK
325
+ (`packages/service/README.md`) is the reference for behaviour — the wire is
326
+ identical, and a Python service and a TS service draw the same surfaces.
327
+
328
+ **The one difference is the typing of the props, not the behaviour.**
329
+ `create_ui[Props]` and `RequenceUI[Props]` take a type parameter, but
330
+ `ctx.render(ui, props)` accepts `Any`: a wrong prop name or a wrong value type is a
331
+ runtime concern here, where TypeScript catches it against `Partial<Props>`. There is
332
+ also no type bridge between the service and the component — no `PropsOf`, no
333
+ `createSurface` — because a component is always a built JavaScript module (see
334
+ below), so its props are declared in TypeScript on the component's side and in
335
+ Python on the service's side, and keeping the two in step is yours. Everything else
336
+ in this section behaves exactly as the TS README describes it.
337
+
338
+ ```python
339
+ from pathlib import Path
340
+ from requence.service import Service, create_ui
341
+
342
+ ui = create_ui(
343
+ # An ABSOLUTE path to the BUILT component. `Path(__file__).parent / …`
344
+ # resolves against this module, not against whatever directory the service was
345
+ # started from.
346
+ Path(__file__).parent / "dist" / "panel.js",
347
+ # Optional default props: what does not change from one message to the next.
348
+ {"dense": True},
349
+ )
350
+
351
+ def handler(ctx):
352
+ ctx.render(ui, {"title": "Processing"})
353
+ return ctx.input
354
+
355
+ Service("1.0.0", handler)
356
+ ```
357
+
358
+ **Requence never bundles.** The component is always a built JavaScript ES module
359
+ with one default `mount(element, ctx)` export, whatever language the service is
360
+ written in — build it with your own JS toolchain and point `create_ui` at the
361
+ result. The bundle is read and hashed once, at import time, and capped at 1 MiB,
362
+ so an oversized component fails at startup rather than on its first render in
363
+ production.
364
+
365
+ ### `create_ui(path, defaults=None, *, id=None)`
366
+
367
+ | Argument | Meaning |
368
+ |---|---|
369
+ | `path` | Absolute path (`str` or `PathLike`) to the built module. A relative path or a URL is refused — the first resolves against the working directory, and Requence reads the component's bytes rather than fetching them. |
370
+ | `defaults` | Props restated on every render of this component. Copied one level deep. |
371
+ | `id` | The component's **stable id**, defaulting to the built file's name. |
372
+
373
+ The id is what a durable handler is addressed by, and it is the one thing about a
374
+ component a rebuild leaves alone — the content hash deliberately does not. Two
375
+ handles claiming one id raise at import time, so two `index.js`-shaped components,
376
+ or one file registered twice with different defaults, need explicit ids.
377
+
378
+ ### `ctx.render(ui, props, *, surface_id="default")`
379
+
380
+ Fire-and-forget, like a data send: the publish is enrolled in the message's ledger,
381
+ so a failure fails the node at the settle gate rather than at the call site.
382
+
383
+ **A render is a patch.** What the surface shows is the *fold* of three layers — the
384
+ UI's defaults, everything previously rendered onto that surface, and this render —
385
+ so redrawing one field takes one prop and leaves the rest standing:
386
+
387
+ ```python
388
+ ctx.render(ui, {"title": "Processing", "at": now()})
389
+ ctx.render(ui, {"at": now()}) # still says "Processing"
390
+ ctx.render(ui, {"title": "Done"}) # and still carries the last `at`
391
+ ```
392
+
393
+ The merge is **shallow**, and nothing is ever removed — an omitted prop means
394
+ "nothing to say about this", so a prop is taken back by saying something else about
395
+ it (`{"error": None}`). Defaults are the **weakest** layer: they are what a surface
396
+ shows until some render says otherwise.
397
+
398
+ `surface_id` names which surface on the node this render targets; one node can
399
+ carry several.
400
+
401
+ **Prop names are the component's, not Python's.** The props are a wire contract with
402
+ a built JavaScript module, so they stay in whatever case that module reads —
403
+ `onSubmit`, not `on_submit`. Nothing here renames anything, in either direction, and
404
+ the same is true of the argument an interaction comes back with: the component decides
405
+ what it sends, and the handler receives exactly that.
406
+
407
+ ### Handler props — where you write the callable decides how long it can be pressed
408
+
409
+ A callable in a surface's props arrives in the component as an invokable function.
410
+ There are **two kinds**, and you pick by *where you write it*:
411
+
412
+ ```python
413
+ def on_submit(answer):
414
+ # DURABLE. Module scope, so any instance of this version can run it — this one,
415
+ # or the one that replaces it in a redeploy. An invocation waits in the
416
+ # version's handler queue for ~60s, so the handler below is free to return, and
417
+ # a rolling restart is invisible to the viewer.
418
+ record(answer)
419
+
420
+ ask_ui = create_ui(HERE / "dist" / "ask.js", {"onSubmit": on_submit})
421
+
422
+ def handler(ctx):
423
+ ctx.render(ask_ui, {
424
+ "question": "ship it?",
425
+ # CONNECTION-BOUND. Closes over this running handler, so only this process
426
+ # can serve it and it dies when the message settles — which is also why it
427
+ # needs a generator handler.
428
+ "onCancel": lambda _arg: ctx.debug.log("cancelled"),
429
+ })
430
+ yield from ()
431
+ ```
432
+
433
+ A **non-generator** handler may not declare a callable in a render's props: its
434
+ registry goes the moment it returns, so the reference would be dead on arrival. It
435
+ raises with that message and names the fix. A callable in the UI's **defaults** is
436
+ durable and registers nothing, so a non-generator handler can publish one freely.
437
+
438
+ A durable handler gets **no injected context**: it reaches its own stores and
439
+ anything else through its own closure, exactly as a module-scope function would in
440
+ any other process of the version. Consuming the handler queue is automatic — it is
441
+ `service-<name>@<version>-handlers`, one per version, created by Requence when the
442
+ version is provisioned and declared again by the SDK on connect.
443
+
444
+ **A durable handler outlives its message, not its task.** The rule the browser
445
+ applies per prop is:
446
+
447
+ ```
448
+ reachable(durable) = the task is running AND some instance of the version is up
449
+ reachable(connection) = …and this surface's connection is alive with the message unsettled
450
+ ```
451
+
452
+ So if the handler that rendered simply **returns**, the node completes, the task goes
453
+ terminal, and the button is correctly reported unreachable and disabled within
454
+ seconds — the surface stays, but there is nothing behind it. A handler that wants its
455
+ controls to keep working calls `ctx.defer(...)`, which settles the message (so no
456
+ connection-bound prop can survive it) and leaves the task running:
457
+
458
+ ```python
459
+ def handler(ctx):
460
+ ctx.defer("waiting for a click")
461
+ ctx.render(ask_ui, {"question": "ship it?"})
462
+ # returns here; the process may now exit and the button still works
463
+ ```
464
+
465
+ The argument comes from the **browser** and is forgeable: validate it in the
466
+ handler, and keep anything the handler must not be told in its closure rather than
467
+ in the props. An interaction is *accepted*, not awaited, so a click carries no
468
+ result — feedback is a re-render.
469
+
470
+ **A thrown handler is visible.** Whatever went wrong — an unregistered component, a
471
+ prop holding nothing invokable, a handler that raised — is recorded on the surface
472
+ and rendered by Requence beneath the frame, and the invocation is **acked** either
473
+ way (a requeue would rerun a side-effecting handler forever).
474
+
475
+ ### Component reload in a dev session
476
+
477
+ A service connected with a **dev token** watches the built file behind every
478
+ `create_ui`. Rebuild it and the frame swaps to the new bundle in place — same
479
+ props, same handlers, same node, no re-render and no new task. It reaches every
480
+ surface your dev session ever drew and nothing else, so a production surface of
481
+ the same component is untouched. Saving the file without changing its content
482
+ swaps nothing, and a rebuild over the 1 MiB cap is refused with a warning while
483
+ the previous bundle stays live.
484
+
485
+ The watch is a poll (one `stat` per registered component every 200 ms) rather than
486
+ a filesystem-event subscription, so the SDK grows no runtime dependency for a
487
+ dev-only feature. It runs on one daemon thread, never holds the process open, and
488
+ an unwatchable path degrades the loop to a warning — you still get a rebuild on
489
+ restart.
490
+
491
+ ### The deferred form, end to end
492
+
493
+ A durable handler answering the node it was rendered on is the shape all of this is
494
+ for. It needs `Service.start(...)`, because the handler is at module scope and has to
495
+ reach the instance:
496
+
497
+ ```python
498
+ def on_submit(arg):
499
+ # Durable: module scope, so any instance of this version can run it. The defer
500
+ # key came out in the props and comes back in the argument.
501
+ def actor(api):
502
+ api["render"](ui, {"submitted": True}) # before the send: act() settles it
503
+ api["send"]({"answer": arg["answer"]})
504
+
505
+ service.act(arg["deferKey"], actor)
506
+
507
+ ui = create_ui(HERE / "dist" / "ask.js", {"onSubmit": on_submit})
508
+
509
+ def handler(ctx):
510
+ # Defer FIRST: there is no key until the message is parked, and deferring is
511
+ # what keeps the task running so the button stays reachable.
512
+ ctx.render(ui, {"question": "ship it?", "deferKey": ctx.defer("waiting")})
513
+
514
+ service = Service.start({"version": "1.0.0"}, handler)
515
+ threading.Event().wait()
516
+ ```
517
+
518
+ Kill the process afterwards and the form still works: answering it runs the handler
519
+ in whichever instance of the version is free at the time, and an invocation with none
520
+ running waits in the version's handler queue. Requence holds nothing.
521
+
522
+ The argument is the **browser's** and forgeable — the `deferKey` above included. That
523
+ is safe because a key is single-use, belongs to that task's own node, and `act()`
524
+ refuses anything else. A handler acting on a viewer-supplied amount, id or address
525
+ must validate it, and anything the handler must not be told belongs in its closure
526
+ rather than in the props.
527
+
528
+ `test/demo-service/surface_demo.py` is this, runnable.
529
+
530
+ ---
531
+
294
532
  ## CLI — `requence-service generate-types`
295
533
 
296
534
  The package installs a `requence-service` CLI that generates Python type stubs from the schemas you defined in the Requence UI:
@@ -99,30 +99,49 @@ Service(
99
99
 
100
100
  The dev token is resolved in the same order as the access token — `dev_token` argument → `REQUENCE_SERVICE_DEV_TOKEN` / `REQUENCE_DEV_TOKEN` env var → `requence.service_dev_token` / `requence.dev_token` in `pyproject.toml`.
101
101
 
102
- ### Closing the service
102
+ ### Two ways to start — and why it matters
103
103
 
104
- `Service.__init__` blocks the current thread (it calls `channel.start_consuming()`). To stop consuming from another thread, call `close()`:
104
+ `Service(...)` configures the service and then **consumes on the calling thread**, so it never returns while the service is up:
105
+
106
+ ```python
107
+ from requence.service import Service
108
+
109
+ Service("1.0.0", lambda ctx: ctx.input) # blocks here forever
110
+ ```
111
+
112
+ That is the right shape when the service is the whole program. But it means there is **no instance to call methods on** — so `act()` and `close()`, which are both methods, are out of reach. Use `Service.start(...)` when you need either. It is the same configuration with the consume loop on a thread of its own, and it **returns the instance** once connected:
105
113
 
106
114
  ```python
107
115
  import threading
108
116
  from requence.service import Service
109
117
 
110
- service = None
118
+ service = Service.start("1.0.0", lambda ctx: ctx.input)
119
+ # ...connected; `service` is usable here
111
120
 
112
- def handler(ctx):
113
- return ctx.input
121
+ threading.Event().wait() # keep the main thread alive; see below
122
+ ```
114
123
 
115
- def run():
116
- global service
117
- service = Service("1.0.0", handler)
124
+ | | `Service(...)` | `Service.start(...)` |
125
+ |---|---|---|
126
+ | Returns | never (while up) | once connected |
127
+ | `act()` / `close()` | unreachable | usable |
128
+ | Bad credentials | raises | raises |
129
+ | Consume thread | the caller's | a daemon thread |
118
130
 
119
- thread = threading.Thread(target=run)
120
- thread.start()
131
+ `start(..., timeout=30.0)` bounds only the **first** connect; every drop after it reconnects in the background as always. A first connect that never lands raises `TimeoutError` and stops retrying, so you never get back an instance you cannot use.
121
132
 
122
- # Later, from another thread:
133
+ Its consume thread is a **daemon**, so it never holds the process open. If the service is the whole program, keep the main thread alive yourself — a `threading.Event().wait()`, a web server, a REPL — or just use the blocking `Service(...)`.
134
+
135
+ ### Closing the service
136
+
137
+ ```python
138
+ service = Service.start("1.0.0", handler)
139
+ # ...later, from anywhere:
123
140
  service.close()
124
141
  ```
125
142
 
143
+ `close()` stops consuming and stops reconnecting. It is safe to call from any thread: the channel work is marshalled onto the connection's own thread.
144
+
126
145
  ---
127
146
 
128
147
  ## Context API
@@ -240,18 +259,18 @@ The generator is stopped automatically when `ctx.terminated` is set. Any yielded
240
259
 
241
260
  ## Deferred Delivery via `service.act()`
242
261
 
243
- After deferring a message with `ctx.defer()`, deliver the result later — even from a different process — using the `act()` method on the `Service` instance:
262
+ After deferring a message with `ctx.defer()`, deliver the result later — even from a different process — using the `act()` method on the `Service` instance.
263
+
264
+ **Start the service with `Service.start(...)`**, not `Service(...)`: `act()` is a method, and the blocking constructor never returns the object to call it on.
244
265
 
245
266
  ```python
246
267
  from requence.service import Service
247
268
 
248
- service = None
249
-
250
269
  def handler(ctx):
251
270
  message_key = ctx.defer()
252
271
  save_to_db(ctx.task_id, message_key)
253
272
 
254
- service = Service("1.0.0", handler) # blocks
273
+ service = Service.start("1.0.0", handler) # returns
255
274
  ```
256
275
 
257
276
  ```python
@@ -266,6 +285,8 @@ def actor(api):
266
285
  service.act(message_key, actor)
267
286
  ```
268
287
 
288
+ `act()` may be called from any thread — a web request handler, a scheduler, a durable surface handler. It publishes through the connection's own thread and does not return until everything it published has actually gone out, so a script that calls `act()` and then exits does not lose the answer.
289
+
269
290
  The `actor` callable receives an `api` dict with three keys:
270
291
 
271
292
  | Key | Description |
@@ -273,11 +294,229 @@ The `actor` callable receives an `api` dict with three keys:
273
294
  | `api["send"](data)` | Send data to the default output |
274
295
  | `api["send_to_output"](name, data)` | Send data to a named output |
275
296
  | `api["abort"](error)` | Abort the deferred message with an error string or exception |
297
+ | `api["render"](ui, props, surface_id=…)` | Draw or redraw a surface on the deferred node — see [Surfaces](#surfaces--a-ui-of-your-own-on-the-node) |
276
298
 
277
299
  The actor can also return a value or a generator directly, which behaves like calling `api["send"]()` for each value.
278
300
 
279
301
  ---
280
302
 
303
+ ## Surfaces — a UI of your own on the node
304
+
305
+ A service can ship its own UI component and have Requence render it **on the
306
+ publishing node** in the task canvas. There is no UI protocol: the contract is
307
+ **props**, and a callable inside them arrives in the component as an invokable
308
+ function.
309
+
310
+ The design authority is
311
+ [`knowledge/service-ui-surfaces.md`](../knowledge/service-ui-surfaces.md); this
312
+ section is the Python API. The TypeScript SDK
313
+ (`packages/service/README.md`) is the reference for behaviour — the wire is
314
+ identical, and a Python service and a TS service draw the same surfaces.
315
+
316
+ **The one difference is the typing of the props, not the behaviour.**
317
+ `create_ui[Props]` and `RequenceUI[Props]` take a type parameter, but
318
+ `ctx.render(ui, props)` accepts `Any`: a wrong prop name or a wrong value type is a
319
+ runtime concern here, where TypeScript catches it against `Partial<Props>`. There is
320
+ also no type bridge between the service and the component — no `PropsOf`, no
321
+ `createSurface` — because a component is always a built JavaScript module (see
322
+ below), so its props are declared in TypeScript on the component's side and in
323
+ Python on the service's side, and keeping the two in step is yours. Everything else
324
+ in this section behaves exactly as the TS README describes it.
325
+
326
+ ```python
327
+ from pathlib import Path
328
+ from requence.service import Service, create_ui
329
+
330
+ ui = create_ui(
331
+ # An ABSOLUTE path to the BUILT component. `Path(__file__).parent / …`
332
+ # resolves against this module, not against whatever directory the service was
333
+ # started from.
334
+ Path(__file__).parent / "dist" / "panel.js",
335
+ # Optional default props: what does not change from one message to the next.
336
+ {"dense": True},
337
+ )
338
+
339
+ def handler(ctx):
340
+ ctx.render(ui, {"title": "Processing"})
341
+ return ctx.input
342
+
343
+ Service("1.0.0", handler)
344
+ ```
345
+
346
+ **Requence never bundles.** The component is always a built JavaScript ES module
347
+ with one default `mount(element, ctx)` export, whatever language the service is
348
+ written in — build it with your own JS toolchain and point `create_ui` at the
349
+ result. The bundle is read and hashed once, at import time, and capped at 1 MiB,
350
+ so an oversized component fails at startup rather than on its first render in
351
+ production.
352
+
353
+ ### `create_ui(path, defaults=None, *, id=None)`
354
+
355
+ | Argument | Meaning |
356
+ |---|---|
357
+ | `path` | Absolute path (`str` or `PathLike`) to the built module. A relative path or a URL is refused — the first resolves against the working directory, and Requence reads the component's bytes rather than fetching them. |
358
+ | `defaults` | Props restated on every render of this component. Copied one level deep. |
359
+ | `id` | The component's **stable id**, defaulting to the built file's name. |
360
+
361
+ The id is what a durable handler is addressed by, and it is the one thing about a
362
+ component a rebuild leaves alone — the content hash deliberately does not. Two
363
+ handles claiming one id raise at import time, so two `index.js`-shaped components,
364
+ or one file registered twice with different defaults, need explicit ids.
365
+
366
+ ### `ctx.render(ui, props, *, surface_id="default")`
367
+
368
+ Fire-and-forget, like a data send: the publish is enrolled in the message's ledger,
369
+ so a failure fails the node at the settle gate rather than at the call site.
370
+
371
+ **A render is a patch.** What the surface shows is the *fold* of three layers — the
372
+ UI's defaults, everything previously rendered onto that surface, and this render —
373
+ so redrawing one field takes one prop and leaves the rest standing:
374
+
375
+ ```python
376
+ ctx.render(ui, {"title": "Processing", "at": now()})
377
+ ctx.render(ui, {"at": now()}) # still says "Processing"
378
+ ctx.render(ui, {"title": "Done"}) # and still carries the last `at`
379
+ ```
380
+
381
+ The merge is **shallow**, and nothing is ever removed — an omitted prop means
382
+ "nothing to say about this", so a prop is taken back by saying something else about
383
+ it (`{"error": None}`). Defaults are the **weakest** layer: they are what a surface
384
+ shows until some render says otherwise.
385
+
386
+ `surface_id` names which surface on the node this render targets; one node can
387
+ carry several.
388
+
389
+ **Prop names are the component's, not Python's.** The props are a wire contract with
390
+ a built JavaScript module, so they stay in whatever case that module reads —
391
+ `onSubmit`, not `on_submit`. Nothing here renames anything, in either direction, and
392
+ the same is true of the argument an interaction comes back with: the component decides
393
+ what it sends, and the handler receives exactly that.
394
+
395
+ ### Handler props — where you write the callable decides how long it can be pressed
396
+
397
+ A callable in a surface's props arrives in the component as an invokable function.
398
+ There are **two kinds**, and you pick by *where you write it*:
399
+
400
+ ```python
401
+ def on_submit(answer):
402
+ # DURABLE. Module scope, so any instance of this version can run it — this one,
403
+ # or the one that replaces it in a redeploy. An invocation waits in the
404
+ # version's handler queue for ~60s, so the handler below is free to return, and
405
+ # a rolling restart is invisible to the viewer.
406
+ record(answer)
407
+
408
+ ask_ui = create_ui(HERE / "dist" / "ask.js", {"onSubmit": on_submit})
409
+
410
+ def handler(ctx):
411
+ ctx.render(ask_ui, {
412
+ "question": "ship it?",
413
+ # CONNECTION-BOUND. Closes over this running handler, so only this process
414
+ # can serve it and it dies when the message settles — which is also why it
415
+ # needs a generator handler.
416
+ "onCancel": lambda _arg: ctx.debug.log("cancelled"),
417
+ })
418
+ yield from ()
419
+ ```
420
+
421
+ A **non-generator** handler may not declare a callable in a render's props: its
422
+ registry goes the moment it returns, so the reference would be dead on arrival. It
423
+ raises with that message and names the fix. A callable in the UI's **defaults** is
424
+ durable and registers nothing, so a non-generator handler can publish one freely.
425
+
426
+ A durable handler gets **no injected context**: it reaches its own stores and
427
+ anything else through its own closure, exactly as a module-scope function would in
428
+ any other process of the version. Consuming the handler queue is automatic — it is
429
+ `service-<name>@<version>-handlers`, one per version, created by Requence when the
430
+ version is provisioned and declared again by the SDK on connect.
431
+
432
+ **A durable handler outlives its message, not its task.** The rule the browser
433
+ applies per prop is:
434
+
435
+ ```
436
+ reachable(durable) = the task is running AND some instance of the version is up
437
+ reachable(connection) = …and this surface's connection is alive with the message unsettled
438
+ ```
439
+
440
+ So if the handler that rendered simply **returns**, the node completes, the task goes
441
+ terminal, and the button is correctly reported unreachable and disabled within
442
+ seconds — the surface stays, but there is nothing behind it. A handler that wants its
443
+ controls to keep working calls `ctx.defer(...)`, which settles the message (so no
444
+ connection-bound prop can survive it) and leaves the task running:
445
+
446
+ ```python
447
+ def handler(ctx):
448
+ ctx.defer("waiting for a click")
449
+ ctx.render(ask_ui, {"question": "ship it?"})
450
+ # returns here; the process may now exit and the button still works
451
+ ```
452
+
453
+ The argument comes from the **browser** and is forgeable: validate it in the
454
+ handler, and keep anything the handler must not be told in its closure rather than
455
+ in the props. An interaction is *accepted*, not awaited, so a click carries no
456
+ result — feedback is a re-render.
457
+
458
+ **A thrown handler is visible.** Whatever went wrong — an unregistered component, a
459
+ prop holding nothing invokable, a handler that raised — is recorded on the surface
460
+ and rendered by Requence beneath the frame, and the invocation is **acked** either
461
+ way (a requeue would rerun a side-effecting handler forever).
462
+
463
+ ### Component reload in a dev session
464
+
465
+ A service connected with a **dev token** watches the built file behind every
466
+ `create_ui`. Rebuild it and the frame swaps to the new bundle in place — same
467
+ props, same handlers, same node, no re-render and no new task. It reaches every
468
+ surface your dev session ever drew and nothing else, so a production surface of
469
+ the same component is untouched. Saving the file without changing its content
470
+ swaps nothing, and a rebuild over the 1 MiB cap is refused with a warning while
471
+ the previous bundle stays live.
472
+
473
+ The watch is a poll (one `stat` per registered component every 200 ms) rather than
474
+ a filesystem-event subscription, so the SDK grows no runtime dependency for a
475
+ dev-only feature. It runs on one daemon thread, never holds the process open, and
476
+ an unwatchable path degrades the loop to a warning — you still get a rebuild on
477
+ restart.
478
+
479
+ ### The deferred form, end to end
480
+
481
+ A durable handler answering the node it was rendered on is the shape all of this is
482
+ for. It needs `Service.start(...)`, because the handler is at module scope and has to
483
+ reach the instance:
484
+
485
+ ```python
486
+ def on_submit(arg):
487
+ # Durable: module scope, so any instance of this version can run it. The defer
488
+ # key came out in the props and comes back in the argument.
489
+ def actor(api):
490
+ api["render"](ui, {"submitted": True}) # before the send: act() settles it
491
+ api["send"]({"answer": arg["answer"]})
492
+
493
+ service.act(arg["deferKey"], actor)
494
+
495
+ ui = create_ui(HERE / "dist" / "ask.js", {"onSubmit": on_submit})
496
+
497
+ def handler(ctx):
498
+ # Defer FIRST: there is no key until the message is parked, and deferring is
499
+ # what keeps the task running so the button stays reachable.
500
+ ctx.render(ui, {"question": "ship it?", "deferKey": ctx.defer("waiting")})
501
+
502
+ service = Service.start({"version": "1.0.0"}, handler)
503
+ threading.Event().wait()
504
+ ```
505
+
506
+ Kill the process afterwards and the form still works: answering it runs the handler
507
+ in whichever instance of the version is free at the time, and an invocation with none
508
+ running waits in the version's handler queue. Requence holds nothing.
509
+
510
+ The argument is the **browser's** and forgeable — the `deferKey` above included. That
511
+ is safe because a key is single-use, belongs to that task's own node, and `act()`
512
+ refuses anything else. A handler acting on a viewer-supplied amount, id or address
513
+ must validate it, and anything the handler must not be told belongs in its closure
514
+ rather than in the props.
515
+
516
+ `test/demo-service/surface_demo.py` is this, runnable.
517
+
518
+ ---
519
+
281
520
  ## CLI — `requence-service generate-types`
282
521
 
283
522
  The package installs a `requence-service` CLI that generates Python type stubs from the schemas you defined in the Requence UI:
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "requence"
7
- version = "0.8.1.dev55"
7
+ version = "0.8.1.dev62"
8
8
  description = "Requence Service"
9
9
  readme = { file = "README.md", content-type = "text/markdown" }
10
10
  authors = [{ name = "Torsten Blindert" }]
@@ -12,7 +12,6 @@ requires-python = ">=3.12"
12
12
  dependencies = [
13
13
  "pika>=1.3.2",
14
14
  "requests>=2.32.2",
15
- "colorama>=0.4.6",
16
15
  "sseclient-py>=1.8.0",
17
16
  # The portable msgpack wire (requence/wire_codec.py). NOT optional: the SDK
18
17
  # declares `wire:msgpack1` in its AMQP client properties, which is a promise