taskwire 0.1.0__tar.gz

taskwire-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Claude Code session artefacts
+.claude/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Node
+node_modules/
+*.tsbuildinfo
+coverage/
+# Not committed, matching the muxws repository's convention.
+/package-lock.json
+
+# VitePress
+docs/.vitepress/cache/
+docs/.vitepress/dist/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+
+# Scratch drivers written while chasing something down
+.scratch/

taskwire-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jure Erznožnik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

taskwire-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.5
+Name: taskwire
+Version: 0.1.0
+Summary: Progress reporting and awaitable dialogs for long-running server-side operations.
+Project-URL: Homepage, https://github.com/velis74/taskwire
+Project-URL: Repository, https://github.com/velis74/taskwire
+Project-URL: Issues, https://github.com/velis74/taskwire/issues
+Project-URL: Documentation, https://docs.velis.si/taskwire/
+Author-email: Jure Erznožnik <jure.erznoznik@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: celery,dialogs,dynamicforms,fastapi,progress,websocket
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: celery
+Requires-Dist: celery>=5.3; extra == 'celery'
+Requires-Dist: nest-asyncio>=1.6; extra == 'celery'
+Provides-Extra: demo
+Requires-Dist: uvicorn>=0.27; extra == 'demo'
+Provides-Extra: dev
+Requires-Dist: coverage; extra == 'dev'
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: hypothesis; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Provides-Extra: muxws
+Requires-Dist: dynamicforms-fastapi-viewsets[muxws]>=0.5.4; extra == 'muxws'
+Requires-Dist: muxws>=0.3.1; extra == 'muxws'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Provides-Extra: viewsets
+Requires-Dist: dynamicforms-fastapi-viewsets>=0.5.4; extra == 'viewsets'
+Description-Content-Type: text/markdown
+
+# <img src="taskwire-icon.svg" alt="" style="width:2.5em; height: 2.5em; vertical-align: middle"> taskwire
+
+Progress reporting and awaitable dialogs for long-running operations, in Python and TypeScript.
+
+A long-running job — an import, a report, a batch — needs to tell whoever started it what it is
+doing while it is doing it, and sometimes needs to ask them something before it can continue.
+taskwire is that conversation, and the four things it carries:
+
+- **progress**, with nested subtasks whose percentages compose correctly rather than overwriting
+  each other, and commits coalesced so a tight loop cannot flood anything;
+- **awaitable dialogs** — the worker asks a question mid-job and blocks until the answer arrives,
+  with the first answer winning across every tab that is looking;
+- **cancellation**, cooperative and sticky, which raises in the worker at its next progress call;
+- **collectable results** — the job parks a file or a value for later collection and *exits*,
+  holding no worker while the record waits.
+
+## The one idea worth knowing
+
+**The store is the truth; a push is only an accelerator.** Every state change is written before
+anything is sent anywhere, so a dropped, coalesced or suppressed push never changes what the next
+read returns. There is no event log, no sequence numbers and no replay: a client is entitled to
+current state, and asking for it is always enough.
+
+## One protocol, three implementations
+
+The layering is the shape of the source tree:
+
+```
+             protocol            documents, envelopes, the six kinds, the state
+                 │               machines, validation.  Knows of no transport.
+     ┌───────────┼───────────┐
+   local        REST         WS         three independent implementations of it
+     │           │           │
+  (none)   fastapi / asgi   muxws       one adapter each, to the world outside
+```
+
+The **protocol** is specified once and depends on nothing. Each **implementation** carries it over
+one medium and is written against the protocol layer alone, never against another implementation.
+Each **adapter** is the thin piece that binds an implementation to a particular framework, and is
+the only place that framework is imported.
+
+| Implementation | Carries the protocol over | Adapter | Needs |
+|---|---|---|---|
+| **local** | the process itself — no wire, no socket, no serialization | none | nothing |
+| **REST** | request/response polling; the baseline everywhere | `contrib.viewsets`, `contrib.fastapi`, `contrib.asgi` | nothing in core |
+| **WS** | one push per envelope down, the six calls up, lowest latency | `contrib.muxws` | [muxws](https://docs.velis.si/muxws/) |
+
+Swapping one for another changes latency and nothing else — no feature, no state, no document.
+Both languages ship the protocol and the operating half, so a browser-only application runs
+operations rather than only watching them; the adapters, the Redis store and the Celery entry are
+Python's, and the polling client and the register are TypeScript's.
+
+## Install
+
+```bash
+pip install taskwire                 # core: no runtime dependencies at all
+pip install "taskwire[redis]"        # cross-process store and backplane
+pip install "taskwire[fastapi]"      # the REST adapter
+pip install "taskwire[viewsets]"     # the REST API as a fastapi-viewsets viewset
+pip install "taskwire[celery]"       # the worker entry point
+pip install "taskwire[muxws]"        # the WebSocket transport
+```
+
+```bash
+npm install taskwire
+```
+
+## The demo
+
+```bash
+pip install -e ".[fastapi,viewsets,demo]" && npm install
+python demo.py                       # then open http://127.0.0.1:5174
+```
+
+A night batch over one book: four back-office jobs that between them exercise progress, nested
+progress, awaitable dialogs, cancellation and collectable results. See [`demo/README.md`](demo/README.md).
+
+## Status
+
+Pre-1.0 and under active construction. The wire format is versioned independently of the package
+(`Envelope.v`), so package semver says nothing about it.
+
+## Links
+
+- [Documentation](https://docs.velis.si/taskwire/)
+- [Repository](https://github.com/velis74/taskwire)
+
+## License
+
+MIT. Copyright (c) 2026 Jure Erznožnik.

taskwire-0.1.0/README.md

@@ -0,0 +1,90 @@
+# <img src="taskwire-icon.svg" alt="" style="width:2.5em; height: 2.5em; vertical-align: middle"> taskwire
+
+Progress reporting and awaitable dialogs for long-running operations, in Python and TypeScript.
+
+A long-running job — an import, a report, a batch — needs to tell whoever started it what it is
+doing while it is doing it, and sometimes needs to ask them something before it can continue.
+taskwire is that conversation, and the four things it carries:
+
+- **progress**, with nested subtasks whose percentages compose correctly rather than overwriting
+  each other, and commits coalesced so a tight loop cannot flood anything;
+- **awaitable dialogs** — the worker asks a question mid-job and blocks until the answer arrives,
+  with the first answer winning across every tab that is looking;
+- **cancellation**, cooperative and sticky, which raises in the worker at its next progress call;
+- **collectable results** — the job parks a file or a value for later collection and *exits*,
+  holding no worker while the record waits.
+
+## The one idea worth knowing
+
+**The store is the truth; a push is only an accelerator.** Every state change is written before
+anything is sent anywhere, so a dropped, coalesced or suppressed push never changes what the next
+read returns. There is no event log, no sequence numbers and no replay: a client is entitled to
+current state, and asking for it is always enough.
+
+## One protocol, three implementations
+
+The layering is the shape of the source tree:
+
+```
+             protocol            documents, envelopes, the six kinds, the state
+                 │               machines, validation.  Knows of no transport.
+     ┌───────────┼───────────┐
+   local        REST         WS         three independent implementations of it
+     │           │           │
+  (none)   fastapi / asgi   muxws       one adapter each, to the world outside
+```
+
+The **protocol** is specified once and depends on nothing. Each **implementation** carries it over
+one medium and is written against the protocol layer alone, never against another implementation.
+Each **adapter** is the thin piece that binds an implementation to a particular framework, and is
+the only place that framework is imported.
+
+| Implementation | Carries the protocol over | Adapter | Needs |
+|---|---|---|---|
+| **local** | the process itself — no wire, no socket, no serialization | none | nothing |
+| **REST** | request/response polling; the baseline everywhere | `contrib.viewsets`, `contrib.fastapi`, `contrib.asgi` | nothing in core |
+| **WS** | one push per envelope down, the six calls up, lowest latency | `contrib.muxws` | [muxws](https://docs.velis.si/muxws/) |
+
+Swapping one for another changes latency and nothing else — no feature, no state, no document.
+Both languages ship the protocol and the operating half, so a browser-only application runs
+operations rather than only watching them; the adapters, the Redis store and the Celery entry are
+Python's, and the polling client and the register are TypeScript's.
+
+## Install
+
+```bash
+pip install taskwire                 # core: no runtime dependencies at all
+pip install "taskwire[redis]"        # cross-process store and backplane
+pip install "taskwire[fastapi]"      # the REST adapter
+pip install "taskwire[viewsets]"     # the REST API as a fastapi-viewsets viewset
+pip install "taskwire[celery]"       # the worker entry point
+pip install "taskwire[muxws]"        # the WebSocket transport
+```
+
+```bash
+npm install taskwire
+```
+
+## The demo
+
+```bash
+pip install -e ".[fastapi,viewsets,demo]" && npm install
+python demo.py                       # then open http://127.0.0.1:5174
+```
+
+A night batch over one book: four back-office jobs that between them exercise progress, nested
+progress, awaitable dialogs, cancellation and collectable results. See [`demo/README.md`](demo/README.md).
+
+## Status
+
+Pre-1.0 and under active construction. The wire format is versioned independently of the package
+(`Envelope.v`), so package semver says nothing about it.
+
+## Links
+
+- [Documentation](https://docs.velis.si/taskwire/)
+- [Repository](https://github.com/velis74/taskwire)
+
+## License
+
+MIT. Copyright (c) 2026 Jure Erznožnik.

taskwire-0.1.0/conformance/README.md

@@ -0,0 +1,10 @@
+# Conformance fixtures
+
+Language-neutral JSON, read **in place** by both `pytest` and `vitest`. There is no copy step and
+there must never be one (TW-PKG-002): a fixture that has to be copied is a fixture that can drift
+between the two languages, and the whole point of this directory is that it cannot.
+
+| Directory | Holds |
+|---|---|
+| `wire/` | One document per file, in the shapes of specification §3. |
+| `sequences/` | Ordered envelope traces a client must apply, with the state expected afterwards. |

taskwire-0.1.0/conformance/wire/aggregate-counts.json

@@ -0,0 +1,20 @@
+{
+  "kind": "aggregate",
+  "document": {
+    "state": "running",
+    "title": {
+      "key": "taskwire.aggregate.title"
+    },
+    "data": {
+      "total": 4,
+      "queued": 1,
+      "running": 3,
+      "waiting_input": 0
+    },
+    "label": {
+      "key": "acme.importer.title",
+      "text": "Importing"
+    },
+    "updated_at": "2026-08-11T09:15:04.250Z"
+  }
+}

taskwire-0.1.0/conformance/wire/aggregate-waiting-input-dominates.json

@@ -0,0 +1,20 @@
+{
+  "kind": "aggregate",
+  "document": {
+    "state": "waiting_input",
+    "title": {
+      "key": "taskwire.aggregate.title"
+    },
+    "data": {
+      "total": 10,
+      "queued": 0,
+      "running": 9,
+      "waiting_input": 1
+    },
+    "label": {
+      "key": "acme.importer.title",
+      "text": "Importing"
+    },
+    "updated_at": "2026-08-11T09:15:04.250Z"
+  }
+}

taskwire-0.1.0/conformance/wire/dialog-request-open.json

@@ -0,0 +1,37 @@
+{
+  "kind": "dialog_request",
+  "document": {
+    "id": "0d9c8b7a-6543-4210-9fed-cba987654321",
+    "dialog_id": "acme.import.conflict",
+    "buttons": [
+      {
+        "id": "overwrite",
+        "label": {
+          "key": "acme.import.overwrite"
+        },
+        "style": "primary"
+      },
+      {
+        "id": "skip",
+        "label": {
+          "key": "acme.import.skip"
+        }
+      }
+    ],
+    "inputs": [
+      {
+        "name": "comment",
+        "type": "string",
+        "required": false,
+        "label": {
+          "key": "acme.import.note"
+        }
+      }
+    ],
+    "params": {
+      "file": "rows.csv"
+    },
+    "state": "open",
+    "created_at": "2026-08-11T09:15:00.000Z"
+  }
+}

taskwire-0.1.0/conformance/wire/envelope-cancel.json

@@ -0,0 +1,10 @@
+{
+  "kind": "envelope",
+  "document": {
+    "v": 1,
+    "token": "6b1f1c9e-0f2a-4a7d-9c2e-5f5b6a7c8d90",
+    "rev": 1786439700135,
+    "kind": "cancel",
+    "body": {}
+  }
+}

taskwire-0.1.0/conformance/wire/envelope-progress.json

@@ -0,0 +1,34 @@
+{
+  "kind": "envelope",
+  "document": {
+    "v": 1,
+    "token": "6b1f1c9e-0f2a-4a7d-9c2e-5f5b6a7c8d90",
+    "rev": 1786439700123,
+    "kind": "progress",
+    "body": {
+      "state": "running",
+      "percent": 42.5,
+      "data": {
+        "rows_done": 510,
+        "rows_total": 1200
+      },
+      "result_kind": "acme.import.report",
+      "origin_session": "account:42",
+      "origin_connection": "conn-7",
+      "created_at": "2026-08-11T09:15:00.000Z",
+      "updated_at": "2026-08-11T09:15:04.250Z",
+      "title": {
+        "key": "acme.importer.title",
+        "text": "Importing"
+      },
+      "label": {
+        "key": "acme.importer.rows",
+        "params": {
+          "rows": 1200
+        },
+        "text": "Importing 1200 rows"
+      },
+      "icon": "upload"
+    }
+  }
+}

taskwire-0.1.0/conformance/wire/envelope-snapshot.json

@@ -0,0 +1,43 @@
+{
+  "kind": "envelope",
+  "document": {
+    "v": 1,
+    "token": "6b1f1c9e-0f2a-4a7d-9c2e-5f5b6a7c8d90",
+    "rev": 1786439700123,
+    "kind": "snapshot",
+    "body": {
+      "v": 1,
+      "token": "6b1f1c9e-0f2a-4a7d-9c2e-5f5b6a7c8d90",
+      "rev": 1786439700123,
+      "progress": {
+        "state": "running",
+        "percent": 42.5,
+        "data": {
+          "rows_done": 510,
+          "rows_total": 1200
+        },
+        "result_kind": "acme.import.report",
+        "origin_session": "account:42",
+        "origin_connection": "conn-7",
+        "created_at": "2026-08-11T09:15:00.000Z",
+        "updated_at": "2026-08-11T09:15:04.250Z",
+        "title": {
+          "key": "acme.importer.title",
+          "text": "Importing"
+        },
+        "label": {
+          "key": "acme.importer.rows",
+          "params": {
+            "rows": 1200
+          },
+          "text": "Importing 1200 rows"
+        },
+        "icon": "upload"
+      },
+      "dialogs": [],
+      "cancel_requested": false,
+      "server_time": "2026-08-11T09:15:04.317Z",
+      "poll_after_ms": 400
+    }
+  }
+}

taskwire-0.1.0/conformance/wire/error-dispatch-failed.json

@@ -0,0 +1,11 @@
+{
+  "kind": "error",
+  "document": {
+    "code": "dispatch_failed",
+    "message": {
+      "key": "taskwire.error.dispatch_failed",
+      "text": "Could not dispatch the task"
+    },
+    "retryable": true
+  }
+}

taskwire-0.1.0/conformance/wire/progress-percent-absent.json

@@ -0,0 +1,27 @@
+{
+  "kind": "progress",
+  "document": {
+    "state": "running",
+    "data": {
+      "rows_done": 510,
+      "rows_total": 1200
+    },
+    "result_kind": "acme.import.report",
+    "origin_session": "account:42",
+    "origin_connection": "conn-7",
+    "created_at": "2026-08-11T09:15:00.000Z",
+    "updated_at": "2026-08-11T09:15:04.250Z",
+    "title": {
+      "key": "acme.importer.title",
+      "text": "Importing"
+    },
+    "label": {
+      "key": "acme.importer.rows",
+      "params": {
+        "rows": 1200
+      },
+      "text": "Importing 1200 rows"
+    },
+    "icon": "upload"
+  }
+}

taskwire-0.1.0/conformance/wire/progress-percent-null.json

@@ -0,0 +1,28 @@
+{
+  "kind": "progress",
+  "document": {
+    "state": "running",
+    "percent": null,
+    "data": {
+      "rows_done": 510,
+      "rows_total": 1200
+    },
+    "result_kind": "acme.import.report",
+    "origin_session": "account:42",
+    "origin_connection": "conn-7",
+    "created_at": "2026-08-11T09:15:00.000Z",
+    "updated_at": "2026-08-11T09:15:04.250Z",
+    "title": {
+      "key": "acme.importer.title",
+      "text": "Importing"
+    },
+    "label": {
+      "key": "acme.importer.rows",
+      "params": {
+        "rows": 1200
+      },
+      "text": "Importing 1200 rows"
+    },
+    "icon": "upload"
+  }
+}

taskwire-0.1.0/conformance/wire/progress-private.json

@@ -0,0 +1,28 @@
+{
+  "kind": "progress",
+  "document": {
+    "state": "running",
+    "percent": 42.5,
+    "data": {
+      "rows_done": 510,
+      "rows_total": 1200
+    },
+    "result_kind": null,
+    "origin_session": "session:anon-9f",
+    "origin_connection": null,
+    "created_at": "2026-08-11T09:15:00.000Z",
+    "updated_at": "2026-08-11T09:15:04.250Z",
+    "title": {
+      "key": "acme.importer.title",
+      "text": "Importing"
+    },
+    "label": {
+      "key": "acme.importer.rows",
+      "params": {
+        "rows": 1200
+      },
+      "text": "Importing 1200 rows"
+    },
+    "icon": "upload"
+  }
+}

taskwire-0.1.0/conformance/wire/progress-shared-origins.json

@@ -0,0 +1,28 @@
+{
+  "kind": "progress",
+  "document": {
+    "state": "running",
+    "percent": 42.5,
+    "data": {
+      "rows_done": 510,
+      "rows_total": 1200
+    },
+    "result_kind": "acme.import.report",
+    "origin_session": "account:42",
+    "origin_connection": "conn-7",
+    "created_at": "2026-08-11T09:15:00.000Z",
+    "updated_at": "2026-08-11T09:15:04.250Z",
+    "title": {
+      "key": "acme.importer.title",
+      "text": "Importing"
+    },
+    "label": {
+      "key": "acme.importer.rows",
+      "params": {
+        "rows": 1200
+      },
+      "text": "Importing 1200 rows"
+    },
+    "icon": "upload"
+  }
+}

taskwire-0.1.0/conformance/wire/progress-state-cancelled.json

@@ -0,0 +1,28 @@
+{
+  "kind": "progress",
+  "document": {
+    "state": "cancelled",
+    "percent": 51.0,
+    "data": {
+      "rows_done": 510,
+      "rows_total": 1200
+    },
+    "result_kind": "acme.import.report",
+    "origin_session": "account:42",
+    "origin_connection": "conn-7",
+    "created_at": "2026-08-11T09:15:00.000Z",
+    "updated_at": "2026-08-11T09:15:04.250Z",
+    "title": {
+      "key": "acme.importer.title",
+      "text": "Importing"
+    },
+    "label": {
+      "key": "acme.importer.rows",
+      "params": {
+        "rows": 1200
+      },
+      "text": "Importing 1200 rows"
+    },
+    "icon": "upload"
+  }
+}

taskwire-0.1.0/conformance/wire/progress-state-done.json

@@ -0,0 +1,28 @@
+{
+  "kind": "progress",
+  "document": {
+    "state": "done",
+    "percent": 100.0,
+    "data": {
+      "rows_done": 510,
+      "rows_total": 1200
+    },
+    "result_kind": "acme.import.report",
+    "origin_session": "account:42",
+    "origin_connection": "conn-7",
+    "created_at": "2026-08-11T09:15:00.000Z",
+    "updated_at": "2026-08-11T09:15:04.250Z",
+    "title": {
+      "key": "acme.importer.title",
+      "text": "Importing"
+    },
+    "label": {
+      "key": "acme.importer.rows",
+      "params": {
+        "rows": 1200
+      },
+      "text": "Importing 1200 rows"
+    },
+    "icon": "upload"
+  }
+}