tasklease 0.1.0__py3-none-any.whl

tasklease/__init__.py

@@ -0,0 +1,7 @@
+"""The tasklease client package."""
+
+from importlib.metadata import version
+
+__version__ = version("tasklease")
+
+__all__ = ["__version__"]

tasklease/__main__.py

@@ -0,0 +1,5 @@
+"""Run the tasklease command line interface."""
+
+from tasklease.cli import main
+
+raise SystemExit(main())

tasklease/cli/__init__.py

@@ -0,0 +1,53 @@
+"""The tasklease command line entry point."""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import cast
+
+from tasklease import __version__
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Parse a command without side effects until its handler runs."""
+    from tasklease.cli import (
+        identity,
+        inbox,
+        monitor,
+        requester,
+        service,
+        tasks,
+        topics,
+        worker,
+    )
+    from tasklease.cli.common import message
+    from tasklease.errors import TaskleaseError
+
+    parser = argparse.ArgumentParser(
+        prog="tl", description="A leased task board for agents and workers."
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    parser.add_argument("--config", type=Path)
+    parser.add_argument("--url")
+    parser.add_argument("--worker")
+    commands = parser.add_subparsers(dest="command")
+    for module in (identity, requester, inbox, tasks, topics, service, worker, monitor):
+        module.configure_parser(commands)
+    args = parser.parse_args(argv)
+    selected: object = getattr(args, "handler", None)
+    if selected is None:
+        parser.print_help()
+        return 0
+    handler = cast(Callable[[argparse.Namespace], int], selected)
+    try:
+        return handler(args)
+    except (TaskleaseError, OSError, ValueError) as error:
+        message(str(error))
+        return 1
+    except KeyboardInterrupt:
+        message("Interrupted")
+        return 130

tasklease/cli/common.py

@@ -0,0 +1,87 @@
+"""Shared command configuration and output."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+from tasklease.client import Client
+from tasklease.config import Config, load_config
+from tasklease.errors import ConfigError
+
+
+def connection_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--config", type=Path, default=argparse.SUPPRESS)
+    parser.add_argument("--url", default=argparse.SUPPRESS)
+    parser.add_argument("--worker", default=argparse.SUPPRESS)
+
+
+def optional_text(args: argparse.Namespace, name: str) -> str | None:
+    value: object = getattr(args, name, None)
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise ConfigError(f"{name} must be text")
+    return value
+
+
+def text(args: argparse.Namespace, name: str) -> str:
+    value = optional_text(args, name)
+    if value is None:
+        raise ConfigError(f"{name} is required")
+    return value
+
+
+def flag(args: argparse.Namespace, name: str) -> bool:
+    value: object = getattr(args, name, False)
+    return value is True
+
+
+def duration_seconds(value: str, *, name: str = "Duration") -> int:
+    """Parse a positive duration expressed in seconds, minutes, hours or days."""
+    match = re.fullmatch(r"([0-9]+)(s|m|h|d)", value)
+    if not match or int(match[1]) <= 0:
+        raise ConfigError(
+            f"{name} must be positive seconds, minutes, hours or days, e.g. 3d"
+        )
+    return int(match[1]) * {"s": 1, "m": 60, "h": 3600, "d": 86400}[match[2]]
+
+
+def configuration(args: argparse.Namespace) -> Config:
+    path: object = getattr(args, "config", None)
+    if path is not None and not isinstance(path, (str, Path)):
+        raise ConfigError("config must be a path")
+    return load_config(path)
+
+
+def domain(args: argparse.Namespace, config: Config) -> str:
+    value = optional_text(args, "domain") or config.domain
+    if not value:
+        raise ConfigError("Give a domain or set domain in configuration")
+    return value
+
+
+@contextmanager
+def client(args: argparse.Namespace, *, admin: bool = False) -> Iterator[Client]:
+    config = configuration(args)
+    url = optional_text(args, "url") or config.url
+    if not url:
+        raise ConfigError("Set the service URL in config.toml or use --url")
+    worker = optional_text(args, "worker") or config.worker_label
+    with Client(url, config.token(admin=admin), worker) as api:
+        yield api
+
+
+def output(value: object) -> None:
+    # Escaping also preserves unusual wire JSON strings, including isolated
+    # surrogate code units, without failing at the terminal's UTF-8 boundary.
+    print(json.dumps(value, ensure_ascii=True, allow_nan=False, separators=(",", ":")))
+
+
+def message(value: str) -> None:
+    print(value, file=sys.stderr)

tasklease/cli/identity.py

@@ -0,0 +1,106 @@
+"""Identity administration and inspection."""
+
+from __future__ import annotations
+
+import argparse
+
+from tasklease.cli.common import (
+    client,
+    connection_options,
+    flag,
+    message,
+    optional_text,
+    output,
+    text,
+)
+from tasklease.errors import ConfigError
+
+
+def _globs(args: argparse.Namespace, name: str) -> list[str]:
+    value = optional_text(args, name)
+    if value is None:
+        return []
+    result = value.split(",")
+    if any(not item for item in result):
+        raise ConfigError(f"--{name} contains an empty glob")
+    return result
+
+
+def _add(args: argparse.Namespace) -> int:
+    domains: object = getattr(args, "domain", None)
+    if not isinstance(domains, list):
+        raise ConfigError("Give at least one --domain")
+    checked_domains: list[str] = []
+    for item in domains:
+        if not isinstance(item, str):
+            raise ConfigError("Domain names must be text")
+        checked_domains.append(item)
+    own, create = _globs(args, "own"), _globs(args, "create")
+    with client(args, admin=True) as api:
+        result = api.identity_add(
+            {
+                "name": text(args, "name"),
+                "domains": checked_domains,
+                "scopes": {"own": own, "create": create, "read": _globs(args, "read")},
+                "operator": flag(args, "operator"),
+            }
+        )
+    output(result)
+    added = list(
+        dict.fromkeys(f"{glob}/error" for glob in own if f"{glob}/error" not in create)
+    )
+    if added:
+        message(f"Added create grants: {', '.join(added)}")
+    message("Store the identity token securely; it is shown only once.")
+    return 0
+
+
+def _revoke(args: argparse.Namespace) -> int:
+    with client(args, admin=True) as api:
+        output(api.identity_revoke({"name": text(args, "name")}))
+    return 0
+
+
+def _rotate(args: argparse.Namespace) -> int:
+    with client(args, admin=True) as api:
+        output(api.identity_rotate({"name": text(args, "name")}))
+    message(
+        "Store the replacement token securely; the old token expires within 60 seconds."
+    )
+    return 0
+
+
+def _list(args: argparse.Namespace) -> int:
+    with client(args, admin=True) as api:
+        output(api.identity_list({}))
+    return 0
+
+
+def _whoami(args: argparse.Namespace) -> int:
+    with client(args) as api:
+        output(api.identity_whoami({}))
+    return 0
+
+
+def configure_parser(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    parser = subparsers.add_parser("identity", help="Manage machine identities")
+    commands = parser.add_subparsers(dest="identity_command", required=True)
+    add = commands.add_parser("add", help="Issue an identity token")
+    connection_options(add)
+    add.add_argument("name")
+    add.add_argument("--domain", action="append", required=True)
+    for scope in ("own", "create", "read"):
+        add.add_argument(f"--{scope}", help="Comma-separated topic globs")
+    add.add_argument("--operator", action="store_true")
+    add.set_defaults(handler=_add)
+    for name, handler in (("revoke", _revoke), ("rotate", _rotate), ("list", _list)):
+        command = commands.add_parser(name)
+        connection_options(command)
+        if name != "list":
+            command.add_argument("name")
+        command.set_defaults(handler=handler)
+    whoami = subparsers.add_parser("whoami", help="Show the current identity")
+    connection_options(whoami)
+    whoami.set_defaults(handler=_whoami)

tasklease/cli/inbox.py

@@ -0,0 +1,37 @@
+"""Inspect and prune the machine's durable local reply stores."""
+
+from __future__ import annotations
+
+import argparse
+
+from tasklease.cli.common import connection_options, flag, output
+from tasklease.cli.requester import agent_store
+from tasklease.store import Store
+
+
+def _inbox(args: argparse.Namespace) -> int:
+    stores = (
+        [Store(agent_id) for agent_id in Store.agents()]
+        if flag(args, "all")
+        else [agent_store(args)]
+    )
+    pruned = sum(store.prune() for store in stores) if flag(args, "prune") else None
+    result: dict[str, object] = {
+        "replies": [reply.to_dict() for store in stores for reply in store.inbox()]
+    }
+    if pruned is not None:
+        result["pruned"] = pruned
+    output(result)
+    return 0
+
+
+def configure_parser(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    parser = subparsers.add_parser("inbox", help="List replies saved on this machine")
+    connection_options(parser)
+    parser.add_argument("--all", action="store_true", help="Include every local agent")
+    parser.add_argument(
+        "--prune", action="store_true", help="Remove records over 7 days"
+    )
+    parser.set_defaults(handler=_inbox)

tasklease/cli/monitor.py

@@ -0,0 +1,57 @@
+"""Open a read-only dashboard with credentials kept in this Python process."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import webbrowser
+from pathlib import Path
+
+from tasklease.cli.common import (
+    client,
+    connection_options,
+    flag,
+    message,
+    optional_text,
+    output,
+)
+from tasklease.errors import ConfigError
+from tasklease.monitor.server import MonitorServer, validate_domain_selection
+
+
+def _run(args: argparse.Namespace) -> int:
+    selected_domain = validate_domain_selection(optional_text(args, "domain"))
+    port: object = getattr(args, "port", 0)
+    state_root: object = getattr(args, "state_dir", None)
+    if type(port) is not int or not 0 <= port <= 65535:
+        raise ConfigError("port must be an integer from 0 to 65535")
+    if state_root is not None and not isinstance(state_root, Path):
+        raise ConfigError("state-dir must be a path")
+    with (
+        client(args) as api,
+        MonitorServer(
+            api, port=port, state_root=state_root, domain=selected_domain
+        ) as server,
+    ):
+        output({"url": server.url})
+        message(f"Monitor at {server.url}; press Ctrl-C to stop")
+        sys.stdout.flush()
+        sys.stderr.flush()
+        if not flag(args, "no_browser"):
+            webbrowser.open(server.url)
+        server.serve_forever(poll_interval=0.2)
+    return 0
+
+
+def configure_parser(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    parser = subparsers.add_parser("monitor", help="Open the read-only local dashboard")
+    connection_options(parser)
+    parser.add_argument("--domain", help="Limit service views to an authorized domain")
+    parser.add_argument(
+        "--port", type=int, default=0, help="Local port, default free port"
+    )
+    parser.add_argument("--no-browser", action="store_true")
+    parser.add_argument("--state-dir", type=Path)
+    parser.set_defaults(handler=_run)

tasklease/cli/requester.py

@@ -0,0 +1,197 @@
+"""Durable requester commands and recovery after uncertain submissions."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import cast
+from uuid import uuid4
+
+from tasklease.cli.common import (
+    client,
+    configuration,
+    connection_options,
+    domain,
+    duration_seconds,
+    flag,
+    message,
+    optional_text,
+    output,
+    text,
+)
+from tasklease.client import Client, reject_nonfinite
+from tasklease.errors import ConfigError, TaskleaseError
+from tasklease.store import RequestRecord, Store
+
+
+def agent_store(args: argparse.Namespace) -> Store:
+    """Select a single agent without requiring any network configuration."""
+    agent_id = configuration(args).agent_id
+    if agent_id is None:
+        raise ConfigError("Set agent_id in config.toml or TL_AGENT_ID")
+    return Store(agent_id)
+
+
+def _data(value: str) -> dict[str, object]:
+    if value.startswith("@"):
+        if len(value) == 1:
+            raise ConfigError("--data @file requires a file path")
+        try:
+            value = Path(value[1:]).read_text(encoding="utf-8")
+        except (OSError, UnicodeError):
+            raise ConfigError("Cannot read --data file") from None
+    try:
+        decoded: object = json.loads(value, parse_constant=reject_nonfinite)
+    except (ValueError, UnicodeError, RecursionError):
+        raise ConfigError("--data must contain a valid JSON object") from None
+    if not isinstance(decoded, dict):
+        raise ConfigError("--data must contain a JSON object")
+    return cast(dict[str, object], decoded)
+
+
+def _status(record: RequestRecord) -> None:
+    output(
+        {
+            "request_id": record.request_id,
+            "task_id": record.task_id,
+            "state": record.state,
+        }
+    )
+
+
+def _report_recovery(store: Store, request_id: str) -> None:
+    try:
+        record = store.request(request_id)
+    except (TaskleaseError, OSError, ValueError):
+        return
+    if record is None:
+        return
+    _status(record)
+    if record.state == "submission_unknown":
+        message(
+            "Submission outcome is unknown. Resume with tl wait --request-id "
+            f"{request_id}, or resend with tl request --resend {request_id}. "
+            "Cancellation is unavailable until a task ID is saved."
+        )
+    else:
+        message(
+            f"Request {request_id} remains saved. "
+            f"Resume with tl wait --request-id {request_id}."
+        )
+
+
+def _wait_for(store: Store, api: Client, request_id: str, timeout_seconds: int) -> int:
+    reply = store.wait(api, request_id, timeout_seconds=timeout_seconds)
+    if reply is None:
+        output({"request_id": request_id, "timed_out": True})
+        message(f"Timed out; request {request_id} remains saved for tl wait")
+        return 3
+    output({"request_id": request_id, "data": reply.data, "creator": reply.creator})
+    return 0
+
+
+def _request(args: argparse.Namespace) -> int:
+    timeout = duration_seconds(text(args, "timeout"), name="Timeout")
+    resend = optional_text(args, "resend")
+    if resend is not None:
+        if any(
+            optional_text(args, name) is not None
+            for name in ("domain", "topic", "reply_topic", "data", "request_id")
+        ):
+            raise ConfigError(
+                "--resend uses the saved request; omit --domain, --topic, "
+                "--reply-topic, --data and --request-id"
+            )
+        request_id = resend
+        payload = None
+        selected = topic = reply_topic = None
+    else:
+        selected = domain(args, configuration(args))
+        topic = text(args, "topic")
+        reply_topic = text(args, "reply_topic")
+        payload = _data(text(args, "data"))
+        supplied_id = optional_text(args, "request_id")
+        request_id = uuid4().hex if supplied_id is None else supplied_id
+    store = agent_store(args)
+    with client(args) as api:
+        try:
+            if resend is not None:
+                record = store.resend(api, request_id)
+            else:
+                assert selected is not None and topic is not None
+                assert reply_topic is not None and payload is not None
+                record = store.submit(
+                    api,
+                    selected,
+                    topic,
+                    reply_topic,
+                    payload,
+                    request_id=request_id,
+                )
+            if flag(args, "wait"):
+                return _wait_for(store, api, request_id, timeout)
+        except (TaskleaseError, OSError, ValueError, KeyboardInterrupt):
+            _report_recovery(store, request_id)
+            raise
+        _status(record)
+    return 0
+
+
+def _wait(args: argparse.Namespace) -> int:
+    timeout = duration_seconds(text(args, "timeout"), name="Timeout")
+    store = agent_store(args)
+    with client(args) as api:
+        return _wait_for(store, api, text(args, "request_id"), timeout)
+
+
+def _cancel(args: argparse.Namespace) -> int:
+    store = agent_store(args)
+    request_id = text(args, "request_id")
+    with client(args) as api:
+        result = store.cancel(api, request_id)
+    output(
+        {
+            "request_id": request_id,
+            "cancelled": result == "cancelled",
+            "state": result,
+        }
+    )
+    if result == "submission_unknown":
+        message("Cannot cancel: the submission has no saved task ID; use tl wait")
+        return 1
+    if result == "not_found":
+        message(
+            "Cannot confirm cancellation: the task was already taken or removed. "
+            "The request remains saved for tl wait."
+        )
+        return 1
+    return 0
+
+
+def configure_parser(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    request = subparsers.add_parser("request", help="Submit a durable agent request")
+    connection_options(request)
+    request.add_argument("--domain")
+    request.add_argument("--topic")
+    request.add_argument("--reply-topic")
+    request.add_argument("--data", help="JSON object or @file")
+    identifiers = request.add_mutually_exclusive_group()
+    identifiers.add_argument("--request-id")
+    identifiers.add_argument("--resend", metavar="REQUEST_ID")
+    request.add_argument("--wait", action="store_true")
+    request.add_argument("--timeout", default="6h", help="Wait duration, e.g. 6h")
+    request.set_defaults(handler=_request)
+
+    wait = subparsers.add_parser("wait", help="Wait for a saved request's reply")
+    connection_options(wait)
+    wait.add_argument("--request-id", required=True)
+    wait.add_argument("--timeout", default="6h", help="Wait duration, e.g. 6h")
+    wait.set_defaults(handler=_wait)
+
+    cancel = subparsers.add_parser("cancel", help="Cancel a saved unowned request")
+    connection_options(cancel)
+    cancel.add_argument("--request-id", required=True)
+    cancel.set_defaults(handler=_cancel)