tasklease 0.1.0__py3-none-any.whl

tasklease/cli/service.py

@@ -0,0 +1,169 @@
+"""Operator-facing deployment commands and complete first-use instructions."""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import json
+import os
+import sys
+from pathlib import Path
+
+from tasklease.cloudflare import DeployError, DeployOptions, deploy, status
+from tasklease.config import load_config
+from tasklease.errors import ConfigError
+
+DEPLOY_HELP = """Deploy or upgrade tasklease in your own Cloudflare account.
+
+You need Workers and R2 enabled, and Node.js current LTS (with npx).
+tl uses the exact Wrangler version recorded in its bundled manifest.
+
+1. SIGN IN
+   Run npx --yes wrangler@4.156.0 login once and approve the browser flow.
+   For scripts, use the Cloudflare Edit Cloudflare Workers API token template,
+   export CLOUDFLARE_API_TOKEN, and pass --account-id. The token must permit
+   creating/updating Workers and managing R2 buckets and lifecycle rules.
+
+2. ACCOUNT ID
+   Pass --account-id, set CLOUDFLARE_ACCOUNT_ID, or reuse the saved account.
+   Without one, a single account in Wrangler's OAuth sign-in is selected.
+   Dashboard: Workers & Pages > Account Details > Account ID.
+
+3. R2 SIGNING KEYS
+   Give both TL_R2_ACCESS_KEY_ID and TL_R2_SECRET_ACCESS_KEY, or pass the ID
+   with --r2-access-key-id and enter the secret at the private prompt.
+   On first use, run without keys: tl creates the bucket and Worker, prints
+   and confirms an admin token, then stops with instructions for the keys.
+   In R2 Object Storage > Overview > Account Details > Manage API Tokens,
+   create an Account API token with Object Read & Write permission scoped
+   to the selected bucket. Record the Access Key ID and Secret Access Key.
+   OAuth login credentials cannot sign S3 URLs.
+
+The service uses https://<name>.<subdomain>.workers.dev. Open Workers & Pages
+once if the account has no workers.dev subdomain. --url supplies that address
+when Wrangler cannot report it. No custom domain is needed.
+
+New admin tokens are printed before submission and never saved. Store yours
+in a password manager. If confirmation cannot finish, retain the candidate;
+set TL_ADMIN_TOKEN to it and rerun, or use --rotate-admin-token. A timeout
+does not prove the candidate was rejected or that the old token still works.
+
+On upgrades, TL_ADMIN_TOKEN enables the task and 16-byte R2 upload/download
+check. Without it, the deploy reports that verification was skipped. Probe
+identities are revoked; probe blobs expire under the seven-day lifecycle rule.
+Changing the account or bucket requires a new pair of signing keys.
+
+--config (or TL_CONFIG) selects every config read and write. Unrelated config
+settings are preserved. Nonsecret coordinates are saved after upload so an
+interrupted bootstrap resumes against the same target. --dry-run performs
+read-only inspection and prints the generated Wrangler config and action plan.
+
+Separate test copy:
+  tl service deploy --config /tmp/tl-test.toml --name tasklease-test \\
+                    --bucket tasklease-test-blobs
+
+Exit codes: 0 completed; 4 more input needed; 1 failed.
+"""
+
+
+def _text(args: argparse.Namespace, name: str) -> str | None:
+    value: object = getattr(args, name, None)
+    if value is None:
+        return None
+    if isinstance(value, Path):
+        return str(value)
+    if not isinstance(value, str):
+        raise DeployError(f"Invalid {name} argument.", 4)
+    return value
+
+
+def _run_deploy(args: argparse.Namespace) -> int:
+    try:
+        environment = dict(os.environ)
+        key_id = _text(args, "r2_access_key_id") or environment.get(
+            "TL_R2_ACCESS_KEY_ID"
+        )
+        if (
+            key_id
+            and not environment.get("TL_R2_SECRET_ACCESS_KEY")
+            and sys.stdin.isatty()
+        ):
+            environment["TL_R2_SECRET_ACCESS_KEY"] = getpass.getpass(
+                "R2 Secret Access Key: "
+            )
+        result = deploy(
+            DeployOptions(
+                account_id=_text(args, "account_id"),
+                name=_text(args, "name"),
+                bucket=_text(args, "bucket"),
+                r2_access_key_id=key_id,
+                url=_text(args, "url"),
+                rotate_admin_token=bool(getattr(args, "rotate_admin_token", False)),
+                dry_run=bool(getattr(args, "dry_run", False)),
+            ),
+            load_config(_text(args, "config"), environ=environment),
+            environ=environment,
+        )
+    except DeployError as exc:
+        print(str(exc), file=sys.stderr)
+        return exc.exit_code
+    except (ConfigError, OSError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 4 if isinstance(exc, ConfigError) else 1
+    print(json.dumps(result))
+    return 0
+
+
+def _run_status(args: argparse.Namespace) -> int:
+    try:
+        environment = dict(os.environ)
+        override = _text(args, "url")
+        if override is not None:
+            environment["TL_URL"] = override
+        result = status(
+            load_config(_text(args, "config"), environ=environment),
+            environ=environment,
+        )
+    except DeployError as exc:
+        print(str(exc), file=sys.stderr)
+        return exc.exit_code
+    except (ConfigError, OSError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 4 if isinstance(exc, ConfigError) else 1
+    print(json.dumps(result))
+    return 0
+
+
+def configure_parser(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    service = subparsers.add_parser("service", help="deploy or inspect the service")
+    commands = service.add_subparsers(dest="service_command", required=True)
+    deployment = commands.add_parser(
+        "deploy",
+        help="deploy or upgrade the bundled Worker",
+        description=DEPLOY_HELP,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    for name, help_text in (
+        ("account-id", "Cloudflare account ID"),
+        ("name", "Worker name"),
+        ("bucket", "R2 bucket name"),
+        ("r2-access-key-id", "R2 signing access key ID"),
+        ("url", "HTTPS workers.dev address when Wrangler cannot report it"),
+        ("config", "tasklease config file (or TL_CONFIG)"),
+    ):
+        deployment.add_argument(f"--{name}", help=help_text, default=argparse.SUPPRESS)
+    deployment.add_argument("--rotate-admin-token", action="store_true")
+    deployment.add_argument("--dry-run", action="store_true")
+    deployment.set_defaults(handler=_run_deploy)
+    inspection = commands.add_parser(
+        "status", help="compare service and installed versions"
+    )
+    inspection.add_argument(
+        "--config", default=argparse.SUPPRESS, help="tasklease config file"
+    )
+    inspection.add_argument(
+        "--url", default=argparse.SUPPRESS, help="service origin to inspect"
+    )
+    inspection.set_defaults(handler=_run_status)

tasklease/cli/tasks.py

@@ -0,0 +1,175 @@
+"""Read, move and prune tasks using their current fenced handles."""
+
+from __future__ import annotations
+
+import argparse
+import time
+from collections.abc import Iterator
+
+from tasklease.cli.common import (
+    client,
+    configuration,
+    connection_options,
+    domain,
+    duration_seconds,
+    flag,
+    optional_text,
+    output,
+    text,
+)
+from tasklease.client import Client
+from tasklease.errors import Forbidden, NotFound
+from tasklease.generated.protocol import TasksListRequest, TaskSummary
+
+
+def _tasks(args: argparse.Namespace) -> int:
+    request: TasksListRequest = {
+        "domain": domain(args, configuration(args)),
+        "topic": text(args, "topic"),
+    }
+    cursor = optional_text(args, "cursor")
+    if cursor is not None:
+        request["cursor"] = cursor
+    with client(args) as api:
+        output(api.tasks_list(request))
+    return 0
+
+
+def _read(args: argparse.Namespace) -> int:
+    with client(args) as api:
+        output(
+            api.read(
+                {
+                    "domain": domain(args, configuration(args)),
+                    "topic": text(args, "topic"),
+                    "id": text(args, "id"),
+                }
+            )
+        )
+    return 0
+
+
+def _delete(args: argparse.Namespace) -> int:
+    with client(args) as api:
+        output(
+            api.delete(
+                {
+                    "domain": domain(args, configuration(args)),
+                    "topic": text(args, "topic"),
+                    "id": text(args, "id"),
+                }
+            )
+        )
+    return 0
+
+
+def _pollers(args: argparse.Namespace) -> int:
+    with client(args) as api:
+        output(
+            api.topic_pollers(
+                {
+                    "domain": domain(args, configuration(args)),
+                    "topic": text(args, "topic"),
+                }
+            )
+        )
+    return 0
+
+
+def _move(args: argparse.Namespace) -> int:
+    selected, topic, task_id = (
+        domain(args, configuration(args)),
+        text(args, "topic"),
+        text(args, "id"),
+    )
+    with client(args) as api:
+        task = api.read({"domain": selected, "topic": topic, "id": task_id})["task"]
+        output(
+            api.consume(
+                {
+                    "domain": selected,
+                    "topic": topic,
+                    "id": task["id"],
+                    "tasks": [{"topic": text(args, "to"), "data": task["data"]}],
+                }
+            )
+        )
+    return 0
+
+
+def _age(value: str) -> int:
+    return duration_seconds(value, name="Age") * 1000
+
+
+def _pages(api: Client, selected: str, topic: str) -> Iterator[TaskSummary]:
+    request: TasksListRequest = {"domain": selected, "topic": topic}
+    while True:
+        page = api.tasks_list(request)
+        yield from page["tasks"]
+        cursor = page.get("cursor")
+        if cursor is None:
+            return
+        request["cursor"] = cursor
+
+
+def _prune(args: argparse.Namespace) -> int:
+    selected = domain(args, configuration(args))
+    cutoff = time.time_ns() // 1_000_000 - _age(text(args, "lease_older_than"))
+    deleted = skipped = 0
+    with client(args) as api:
+        topics = api.topics_list({"domain": selected, "glob": text(args, "topic")})[
+            "topics"
+        ]
+        for topic in topics:
+            for task in _pages(api, selected, topic["topic"]):
+                if task["lease_until"] >= cutoff or (
+                    task["owned_count"] == 0 and not flag(args, "all")
+                ):
+                    continue
+                try:
+                    api.delete(
+                        {
+                            "domain": selected,
+                            "topic": topic["topic"],
+                            "id": task["id"],
+                            "lease_before": cutoff,
+                        }
+                    )
+                except (NotFound, Forbidden):
+                    skipped += 1
+                else:
+                    deleted += 1
+    output({"ok": True, "deleted": deleted, "skipped": skipped})
+    return 0
+
+
+def configure_parser(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    for name, handler in (
+        ("tasks", _tasks),
+        ("read", _read),
+        ("delete", _delete),
+        ("pollers", _pollers),
+        ("move", _move),
+    ):
+        parser = subparsers.add_parser(name)
+        connection_options(parser)
+        parser.add_argument("domain")
+        parser.add_argument("topic")
+        if name in {"read", "delete", "move"}:
+            parser.add_argument("id")
+        if name == "tasks":
+            parser.add_argument("--cursor")
+        if name == "move":
+            parser.add_argument("--to", required=True)
+        parser.set_defaults(handler=handler)
+    prune = subparsers.add_parser("prune", help="Remove abandoned tasks by age")
+    connection_options(prune)
+    prune.add_argument("domain")
+    prune.add_argument("--topic", required=True, help="Topic glob")
+    prune.add_argument("--lease-older-than", required=True)
+    prune.add_argument(
+        "--all", action="store_true", help="Also include never-owned tasks"
+    )
+    prune.set_defaults(handler=_prune)

tasklease/cli/topics.py

@@ -0,0 +1,65 @@
+"""Topic discovery and declarations."""
+
+from __future__ import annotations
+
+import argparse
+
+from tasklease.cli.common import (
+    client,
+    configuration,
+    connection_options,
+    domain,
+    flag,
+    optional_text,
+    output,
+    text,
+)
+from tasklease.generated.protocol import TopicsListRequest
+
+
+def _topics(args: argparse.Namespace) -> int:
+    selected = optional_text(args, "domain")
+    with client(args) as api:
+        domains = [selected] if selected else api.identity_whoami({})["domains"]
+        results: list[object] = []
+        for name in domains:
+            request: TopicsListRequest = {"domain": name}
+            glob = optional_text(args, "glob")
+            if glob is not None:
+                request["glob"] = glob
+            results.append({"domain": name, **api.topics_list(request)})
+    output(results)
+    return 0
+
+
+def _declare(args: argparse.Namespace) -> int:
+    config = configuration(args)
+    with client(args) as api:
+        output(
+            api.topic_declare(
+                {
+                    "domain": domain(args, config),
+                    "topic": text(args, "topic"),
+                    "declared": not flag(args, "remove"),
+                }
+            )
+        )
+    return 0
+
+
+def configure_parser(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    topics = subparsers.add_parser("topics", help="List topics across domains")
+    connection_options(topics)
+    topics.add_argument("--domain")
+    topics.add_argument("--glob")
+    topics.set_defaults(handler=_topics)
+    topic = subparsers.add_parser("topic", help="Declare well-known topics")
+    commands = topic.add_subparsers(dest="topic_command", required=True)
+    declare = commands.add_parser("declare")
+    connection_options(declare)
+    declare.add_argument("domain")
+    declare.add_argument("topic")
+    declare.add_argument("--remove", action="store_true", help="Remove the declaration")
+    declare.set_defaults(handler=_declare)

tasklease/cli/worker.py

@@ -0,0 +1,186 @@
+"""Run a generic worker or request a graceful local stop."""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import sys
+from collections.abc import Callable
+from importlib.resources import files
+from pathlib import Path
+from threading import TIMEOUT_MAX
+from typing import cast
+
+from tasklease.cli.common import (
+    client,
+    configuration,
+    connection_options,
+    duration_seconds,
+    flag,
+    optional_text,
+    output,
+    text,
+)
+from tasklease.errors import ConfigError
+from tasklease.worker import (
+    EchoHandler,
+    Handler,
+    UnlimitedCapacity,
+    WorkerLoop,
+    validate_work_topic,
+)
+from tasklease.worker_control import WorkerControl, request_stop
+
+_TEMPLATES = {
+    "systemd": "systemd.service",
+    "launchd": "launchd.plist",
+    "windows": "windows.xml",
+    "windows-stop": "windows-stop.ps1",
+}
+
+
+def _template(args: argparse.Namespace) -> int:
+    resource = files("tasklease").joinpath(
+        "worker_templates", _TEMPLATES[text(args, "platform")]
+    )
+    sys.stdout.write(resource.read_text(encoding="utf-8"))
+    return 0
+
+
+def _table(values: dict[str, object]) -> dict[str, object]:
+    value = values.get("worker", {})
+    if not isinstance(value, dict):
+        raise ConfigError("worker must be a TOML table")
+    return cast(dict[str, object], value)
+
+
+def _setting(
+    args: argparse.Namespace, settings: dict[str, object], name: str, default: object
+) -> object:
+    selected: object = getattr(
+        args, "worker_handler" if name == "handler" else name, None
+    )
+    return settings.get(name, default) if selected is None else selected
+
+
+def _text(value: object, name: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise ConfigError(f"worker {name} must be a nonempty string")
+    return value
+
+
+def _seconds(value: object, name: str) -> int:
+    if type(value) is int and value > 0:
+        return value
+    if isinstance(value, str):
+        return duration_seconds(value, name=name)
+    raise ConfigError(f"worker {name} must be positive seconds or a duration")
+
+
+def _handler(value: str) -> Handler[object, object]:
+    if value == "echo":
+        return cast(Handler[object, object], EchoHandler())
+    module_name, separator, factory_name = value.partition(":")
+    if not separator or not module_name or not factory_name.isidentifier():
+        raise ConfigError("worker handler must be echo or module:factory")
+    try:
+        module = importlib.import_module(module_name)
+        factory: object = getattr(module, factory_name)
+        if not callable(factory):
+            raise TypeError("Factory is not callable")
+        instance = cast(Callable[[], object], factory)()
+    except Exception:
+        raise ConfigError(f"Cannot load worker handler {value}") from None
+    if not all(
+        callable(getattr(instance, name, None)) for name in ("validate", "run", "reply")
+    ):
+        raise ConfigError("worker handler must provide validate, run and reply")
+    return cast(Handler[object, object], instance)
+
+
+def _root(args: argparse.Namespace) -> Path | None:
+    value: object = getattr(args, "state_dir", None)
+    if value is not None and not isinstance(value, Path):
+        raise ConfigError("state-dir must be a path")
+    return value
+
+
+def _stop(args: argparse.Namespace) -> int:
+    label = optional_text(args, "worker") or configuration(args).worker_label
+    path = request_stop(label, _root(args))
+    output({"ok": True, "worker": label, "stop_file": str(path)})
+    return 0
+
+
+def _run(args: argparse.Namespace) -> int:
+    config = configuration(args)
+    settings = _table(config.values)
+    selected = _text(optional_text(args, "domain") or config.domain, "domain")
+    topic = validate_work_topic(_text(_setting(args, settings, "topic", None), "topic"))
+    lease = _seconds(_setting(args, settings, "lease", 600), "lease")
+    renew = _seconds(_setting(args, settings, "renew_every", 180), "renew_every")
+    poll = _seconds(_setting(args, settings, "poll_interval", 30), "poll_interval")
+    if poll > TIMEOUT_MAX / 1.2:
+        raise ConfigError("worker poll_interval exceeds this platform's timer limit")
+    maximum = _setting(args, settings, "max_owned", 3)
+    if type(maximum) is not int or maximum <= 0:
+        raise ConfigError("worker max_owned must be a positive integer")
+    if lease > 86400 or renew >= lease:
+        raise ConfigError(
+            "worker lease must be at most 86400s and renew_every below lease"
+        )
+    handler = _handler(_text(_setting(args, settings, "handler", "echo"), "handler"))
+    label = optional_text(args, "worker") or config.worker_label
+    with WorkerControl(label, _root(args)) as control:
+        if control.stop.is_set():
+            return 0
+        with client(args) as api:
+            capacity = UnlimitedCapacity()
+            loop = WorkerLoop(
+                api,
+                selected,
+                topic,
+                capacity,
+                handler,
+                lease=lease,
+                renew_every=renew,
+                max_owned=maximum,
+                poll_interval=poll,
+                stop=control.stop,
+            )
+            if flag(args, "once"):
+                with capacity.acquire():
+                    result = loop.step()
+                output({"status": result})
+            else:
+                loop.run()
+    return 0
+
+
+def configure_parser(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    parser = subparsers.add_parser("worker", help="Run an echo or plugin worker")
+    connection_options(parser)
+    parser.add_argument("--domain")
+    parser.add_argument("--topic")
+    parser.add_argument(
+        "--handler", dest="worker_handler", help="echo or module:factory"
+    )
+    parser.add_argument("--lease", help="Lease duration, default 600s")
+    parser.add_argument("--renew-every", help="Renew interval, default 180s")
+    parser.add_argument("--max-owned", type=int)
+    parser.add_argument("--poll-interval", help="Idle poll duration, default 30s")
+    parser.add_argument("--once", action="store_true", help="Own at most one task")
+    parser.add_argument("--state-dir", type=Path)
+    parser.set_defaults(handler=_run)
+    commands = parser.add_subparsers(dest="worker_command")
+    stop = commands.add_parser("stop", help="Request a graceful stop without a token")
+    connection_options(stop)
+    stop.add_argument("--state-dir", type=Path, default=argparse.SUPPRESS)
+    stop.set_defaults(handler=_stop)
+    template = commands.add_parser(
+        "template", help="Print a user-worker startup template for editing"
+    )
+    template.add_argument("--platform", choices=tuple(_TEMPLATES), required=True)
+    template.set_defaults(handler=_template)