tasklease 0.1.0__py3-none-any.whl

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 (48) hide show
  1. tasklease/__init__.py +7 -0
  2. tasklease/__main__.py +5 -0
  3. tasklease/cli/__init__.py +53 -0
  4. tasklease/cli/common.py +87 -0
  5. tasklease/cli/identity.py +106 -0
  6. tasklease/cli/inbox.py +37 -0
  7. tasklease/cli/monitor.py +57 -0
  8. tasklease/cli/requester.py +197 -0
  9. tasklease/cli/service.py +169 -0
  10. tasklease/cli/tasks.py +175 -0
  11. tasklease/cli/topics.py +65 -0
  12. tasklease/cli/worker.py +186 -0
  13. tasklease/client.py +283 -0
  14. tasklease/cloudflare/__init__.py +6 -0
  15. tasklease/cloudflare/bundle.py +78 -0
  16. tasklease/cloudflare/deployer.py +714 -0
  17. tasklease/cloudflare/wrangler.py +300 -0
  18. tasklease/config.py +206 -0
  19. tasklease/errors.py +89 -0
  20. tasklease/fsio.py +275 -0
  21. tasklease/generated/__init__.py +1 -0
  22. tasklease/generated/protocol.py +478 -0
  23. tasklease/monitor/__init__.py +1 -0
  24. tasklease/monitor/server.py +325 -0
  25. tasklease/monitor/static/THIRD_PARTY_NOTICES.md +25 -0
  26. tasklease/monitor/static/assets/index-ClHk7fvq.css +1 -0
  27. tasklease/monitor/static/assets/index-CmFr3mRG.js +6 -0
  28. tasklease/monitor/static/index.html +13 -0
  29. tasklease/names.py +60 -0
  30. tasklease/py.typed +0 -0
  31. tasklease/service_bundle/README.md +1 -0
  32. tasklease/service_bundle/THIRD_PARTY_NOTICES.md +2163 -0
  33. tasklease/service_bundle/index.js +18533 -0
  34. tasklease/service_bundle/index.js.map +8 -0
  35. tasklease/service_bundle/manifest.json +4 -0
  36. tasklease/service_bundle/wrangler.template.jsonc +53 -0
  37. tasklease/store.py +669 -0
  38. tasklease/worker.py +444 -0
  39. tasklease/worker_control.py +114 -0
  40. tasklease/worker_templates/launchd.plist +22 -0
  41. tasklease/worker_templates/systemd.service +15 -0
  42. tasklease/worker_templates/windows-stop.ps1 +4 -0
  43. tasklease/worker_templates/windows.xml +27 -0
  44. tasklease-0.1.0.dist-info/METADATA +495 -0
  45. tasklease-0.1.0.dist-info/RECORD +48 -0
  46. tasklease-0.1.0.dist-info/WHEEL +4 -0
  47. tasklease-0.1.0.dist-info/entry_points.txt +2 -0
  48. tasklease-0.1.0.dist-info/licenses/LICENSE +202 -0
@@ -0,0 +1,300 @@
1
+ """Small, version-specific Wrangler subprocess and output boundary."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import os
7
+ import re
8
+ import shutil
9
+ import signal
10
+ import subprocess
11
+ from collections.abc import Mapping, Sequence
12
+ from pathlib import Path
13
+ from typing import cast
14
+ from urllib.parse import urlsplit
15
+
16
+
17
+ class DeployError(Exception):
18
+ """A failed step, or missing operator input."""
19
+
20
+ def __init__(self, message: str, exit_code: int = 1) -> None:
21
+ super().__init__(message)
22
+ self.exit_code = exit_code
23
+
24
+
25
+ def object_value(value: object, label: str) -> dict[str, object]:
26
+ if not isinstance(value, dict) or not all(isinstance(k, str) for k in value):
27
+ raise DeployError(f"Malformed {label}: expected an object.")
28
+ return cast(dict[str, object], value)
29
+
30
+
31
+ def json_value(text: str, label: str) -> object:
32
+ try:
33
+ return cast(object, json.loads(text))
34
+ except ValueError as exc:
35
+ raise DeployError(f"Malformed {label}: expected JSON.") from exc
36
+
37
+
38
+ def string_list(value: object, label: str) -> list[str]:
39
+ if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
40
+ raise DeployError(f"Malformed {label}: expected a string array.")
41
+ return cast(list[str], value)
42
+
43
+
44
+ def _stop_process_tree(process: subprocess.Popen[str]) -> None:
45
+ """Stop the launcher and its children before releasing its temporary project."""
46
+ if os.name == "nt":
47
+ try:
48
+ subprocess.run(
49
+ ["taskkill", "/F", "/T", "/PID", str(process.pid)],
50
+ stdin=subprocess.DEVNULL,
51
+ stdout=subprocess.DEVNULL,
52
+ stderr=subprocess.DEVNULL,
53
+ check=False,
54
+ timeout=5,
55
+ )
56
+ except (OSError, subprocess.TimeoutExpired):
57
+ if process.poll() is None:
58
+ process.kill()
59
+ else:
60
+ try:
61
+ # Kill the group even if npx has already exited and only Node remains.
62
+ os.killpg(process.pid, signal.SIGKILL)
63
+ except ProcessLookupError:
64
+ pass
65
+ try:
66
+ process.communicate(timeout=5)
67
+ except subprocess.TimeoutExpired:
68
+ # A pipe inherited by a detached descendant must not make cleanup hang.
69
+ if process.poll() is None:
70
+ process.kill()
71
+ for pipe in (process.stdin, process.stdout, process.stderr):
72
+ if pipe is not None:
73
+ pipe.close()
74
+ process.wait(timeout=5)
75
+
76
+
77
+ def _run_process(
78
+ command: Sequence[str],
79
+ *,
80
+ cwd: Path,
81
+ environ: Mapping[str, str],
82
+ input_text: str = "",
83
+ timeout: float,
84
+ ) -> subprocess.CompletedProcess[str]:
85
+ """Use one process group for npx's wrapper and the actual Wrangler process."""
86
+ process = subprocess.Popen(
87
+ command,
88
+ cwd=cwd,
89
+ env=environ,
90
+ stdin=subprocess.PIPE,
91
+ stdout=subprocess.PIPE,
92
+ stderr=subprocess.PIPE,
93
+ text=True,
94
+ start_new_session=os.name != "nt",
95
+ )
96
+ try:
97
+ stdout, stderr = process.communicate(input_text, timeout=timeout)
98
+ except BaseException:
99
+ _stop_process_tree(process)
100
+ raise
101
+ return subprocess.CompletedProcess(command, process.returncode, stdout, stderr)
102
+
103
+
104
+ class Wrangler:
105
+ """Run the manifest pin; never put a secret in an argument or file."""
106
+
107
+ def __init__(self, version: str, cwd: Path, environ: Mapping[str, str]) -> None:
108
+ self.version = version
109
+ self.cwd = cwd
110
+ self.environ = dict(environ)
111
+ self.redactions = [
112
+ value
113
+ for key, value in environ.items()
114
+ if value
115
+ and any(
116
+ part in key for part in ("TOKEN", "SECRET", "ACCESS_KEY", "API_KEY")
117
+ )
118
+ ]
119
+ for key in (
120
+ "TL_TOKEN",
121
+ "TL_ADMIN_TOKEN",
122
+ "TL_R2_ACCESS_KEY_ID",
123
+ "TL_R2_SECRET_ACCESS_KEY",
124
+ ):
125
+ self.environ.pop(key, None)
126
+ # The generated top-level config selects the target. These inherited
127
+ # Wrangler settings can otherwise redirect an upload before its output
128
+ # reveals that the wrong Worker was changed.
129
+ self.environ.pop("CLOUDFLARE_ENV", None)
130
+ self.environ.pop("WRANGLER_CI_OVERRIDE_NAME", None)
131
+ self.environ["NO_COLOR"] = "1"
132
+ self.environ["FORCE_COLOR"] = "0"
133
+ self.environ["CI"] = "true"
134
+ self.environ["WRANGLER_SEND_METRICS"] = "false"
135
+ # Wrangler's debug INIT record can contain the complete secret bulk body.
136
+ # Override inherited debug settings to uphold the no-secret-files contract.
137
+ self.environ["WRANGLER_LOG"] = "log"
138
+ self.environ["WRANGLER_LOG_SANITIZE"] = "true"
139
+ self.environ["WRANGLER_WRITE_LOGS"] = "false"
140
+ self.environ["WRANGLER_LOG_PATH"] = str(cwd / "wrangler.log")
141
+ # A caller's output destination must not receive deployment records.
142
+ self.environ.pop("WRANGLER_OUTPUT_FILE_PATH", None)
143
+ self.environ.pop("WRANGLER_OUTPUT_FILE_DIRECTORY", None)
144
+ self.executable = shutil.which("npx", path=environ.get("PATH"))
145
+
146
+ def redact(self, text: str) -> str:
147
+ for value in sorted(self.redactions, key=len, reverse=True):
148
+ text = text.replace(value, "[redacted]")
149
+ return text
150
+
151
+ def check_node(self) -> None:
152
+ node = shutil.which("node", path=self.environ.get("PATH"))
153
+ if node is None or self.executable is None:
154
+ raise DeployError(
155
+ "Install Node.js (current LTS, including npx) before deploying.", 4
156
+ )
157
+ try:
158
+ result = _run_process(
159
+ [node, "--version"],
160
+ timeout=15,
161
+ environ=self.environ,
162
+ cwd=self.cwd,
163
+ )
164
+ except (OSError, subprocess.TimeoutExpired) as exc:
165
+ raise DeployError(
166
+ "Cannot run Node.js; install a current LTS release.", 4
167
+ ) from exc
168
+ match = re.fullmatch(r"v(\d+)\.(\d+)\.\d+\s*", result.stdout)
169
+ if result.returncode or match is None:
170
+ raise DeployError("Cannot determine the installed Node.js version.", 4)
171
+ major, minor = int(match[1]), int(match[2])
172
+ if not ((major == 22 and minor >= 12) or major >= 24):
173
+ raise DeployError("Wrangler requires Node.js 22.12+ or 24+.", 4)
174
+
175
+ def run(
176
+ self,
177
+ args: Sequence[str],
178
+ *,
179
+ secrets: Mapping[str, str] | None = None,
180
+ output_file: Path | None = None,
181
+ timeout: float = 180,
182
+ ) -> str:
183
+ if self.executable is None:
184
+ raise DeployError("npx is unavailable; install Node.js current LTS.", 4)
185
+ environment = self.environ.copy()
186
+ if output_file is not None:
187
+ environment["WRANGLER_OUTPUT_FILE_PATH"] = str(output_file)
188
+ if secrets:
189
+ self.redactions.extend(secrets.values())
190
+ try:
191
+ result = _run_process(
192
+ [self.executable, "--yes", f"wrangler@{self.version}", *args],
193
+ cwd=self.cwd,
194
+ environ=environment,
195
+ input_text=json.dumps(dict(secrets)) if secrets else "",
196
+ timeout=timeout,
197
+ )
198
+ except subprocess.TimeoutExpired as exc:
199
+ raise DeployError(f"Wrangler {' '.join(args[:3])} timed out.") from exc
200
+ except OSError as exc:
201
+ raise DeployError("Cannot start the pinned Wrangler through npx.") from exc
202
+ if result.returncode:
203
+ detail = self.redact((result.stderr + "\n" + result.stdout).strip())
204
+ raise DeployError(f"Wrangler {' '.join(args[:3])} failed:\n{detail}")
205
+ return result.stdout
206
+
207
+
208
+ def labelled_records(text: str, fields: set[str]) -> list[dict[str, str]]:
209
+ """Parse only the pinned CLI's labelled records, rejecting partial records."""
210
+ records: list[dict[str, str]] = []
211
+ current: dict[str, str] = {}
212
+ for line in text.splitlines():
213
+ match = re.match(r"^([a-z_]+):\s*(.*?)\s*$", line)
214
+ if match is None or match[1] not in fields:
215
+ continue
216
+ key, value = match[1], match[2]
217
+ if key == "name" and current:
218
+ if current.keys() != fields:
219
+ raise DeployError("Malformed Wrangler labelled record.")
220
+ records.append(current)
221
+ current = {}
222
+ if key in current:
223
+ raise DeployError("Duplicate field in Wrangler labelled record.")
224
+ current[key] = value
225
+ if current:
226
+ if current.keys() != fields:
227
+ raise DeployError("Incomplete Wrangler labelled record.")
228
+ records.append(current)
229
+ return records
230
+
231
+
232
+ def bucket_names(text: str) -> set[str]:
233
+ records = labelled_records(text, {"name", "creation_date"})
234
+ if not records and "Listing buckets..." not in text:
235
+ raise DeployError("Unrecognized Wrangler bucket list output.")
236
+ return {record["name"] for record in records}
237
+
238
+
239
+ def lifecycle_rules(text: str) -> list[dict[str, str]]:
240
+ records = labelled_records(text, {"name", "enabled", "prefix", "action"})
241
+ if not records and "no lifecycle" not in text.lower():
242
+ raise DeployError("Unrecognized Wrangler lifecycle list output.")
243
+ return records
244
+
245
+
246
+ def secret_names(text: str) -> set[str]:
247
+ value = json_value(text, "Wrangler secret list")
248
+ if not isinstance(value, list):
249
+ raise DeployError("Malformed Wrangler secret list: expected an array.")
250
+ names: set[str] = set()
251
+ for entry in value:
252
+ record = object_value(entry, "secret record")
253
+ name = record.get("name")
254
+ if not isinstance(name, str) or record.get("type") != "secret_text":
255
+ raise DeployError("Malformed Wrangler secret record.")
256
+ names.add(name)
257
+ return names
258
+
259
+
260
+ def worker_url(target: str, name: str) -> str | None:
261
+ try:
262
+ parsed = urlsplit(target if "://" in target else f"https://{target}")
263
+ except ValueError:
264
+ return None
265
+ host = parsed.hostname or ""
266
+ if (
267
+ parsed.scheme != "https"
268
+ or parsed.netloc != host
269
+ or parsed.path not in ("", "/")
270
+ or parsed.query
271
+ or parsed.fragment
272
+ or not re.fullmatch(re.escape(name) + r"\.[a-z0-9-]+\.workers\.dev", host)
273
+ ):
274
+ return None
275
+ return f"https://{host}"
276
+
277
+
278
+ def deployment_url(output_file: Path, name: str, override: str | None) -> str:
279
+ if override:
280
+ url = worker_url(override, name)
281
+ if url is None:
282
+ raise DeployError("--url must be this Worker's HTTPS workers.dev URL.", 4)
283
+ return url
284
+ candidates: set[str] = set()
285
+ if output_file.exists():
286
+ for line in output_file.read_text(encoding="utf-8").splitlines():
287
+ entry = object_value(json_value(line, "Wrangler output event"), "event")
288
+ if entry.get("type") != "deploy":
289
+ continue
290
+ if entry.get("version") != 1 or entry.get("worker_name") != name:
291
+ raise DeployError("Unexpected Wrangler deploy event.")
292
+ for target in string_list(entry.get("targets"), "deploy targets"):
293
+ url = worker_url(target, name)
294
+ if url:
295
+ candidates.add(url)
296
+ if len(candidates) != 1:
297
+ raise DeployError(
298
+ "Wrangler did not report one workers.dev URL; rerun with --url URL.", 4
299
+ )
300
+ return candidates.pop()
tasklease/config.py ADDED
@@ -0,0 +1,206 @@
1
+ """Per-user settings and credentials, with atomic deployment updates."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ import tomllib
7
+ from collections.abc import Mapping
8
+ from dataclasses import dataclass, field
9
+ from pathlib import Path
10
+ from typing import cast
11
+ from urllib.parse import urlsplit
12
+
13
+ import tomli_w
14
+ from platformdirs import user_config_path
15
+
16
+ from tasklease.errors import ConfigError
17
+ from tasklease.fsio import atomic_replace
18
+ from tasklease.names import is_bearer_token, is_domain, is_segment, is_worker_label
19
+
20
+
21
+ def validate_url(value: str) -> str:
22
+ """Validate a service origin and normalize its optional trailing slash."""
23
+ if not isinstance(value, str):
24
+ raise ConfigError("url must be an HTTP or HTTPS service origin")
25
+ try:
26
+ parsed = urlsplit(value)
27
+ port = parsed.port
28
+ valid = (
29
+ parsed.scheme in {"http", "https"}
30
+ and parsed.hostname is not None
31
+ and parsed.username is None
32
+ and parsed.password is None
33
+ and parsed.path in {"", "/"}
34
+ and not parsed.query
35
+ and not parsed.fragment
36
+ and not any(
37
+ character.isspace() or ord(character) < 32 for character in value
38
+ )
39
+ and (port is None or 1 <= port <= 65535)
40
+ )
41
+ except ValueError:
42
+ valid = False
43
+ if not valid:
44
+ raise ConfigError("url must be an HTTP or HTTPS service origin")
45
+ return value.rstrip("/")
46
+
47
+
48
+ def _read_values(path: Path) -> dict[str, object]:
49
+ try:
50
+ with path.open("rb") as source:
51
+ values: dict[str, object] = tomllib.load(source)
52
+ return values
53
+ except FileNotFoundError:
54
+ return {}
55
+ except (tomllib.TOMLDecodeError, UnicodeError):
56
+ raise ConfigError(f"Cannot parse configuration at {path}") from None
57
+ except OSError:
58
+ raise ConfigError(f"Cannot read configuration at {path}") from None
59
+
60
+
61
+ def _token(value: str, source: str) -> str:
62
+ if not is_bearer_token(value):
63
+ raise ConfigError(f"{source} must contain a nonempty bearer token")
64
+ return value
65
+
66
+
67
+ @dataclass
68
+ class Config:
69
+ """Settings from one config file and a snapshot of its environment."""
70
+
71
+ path: Path
72
+ values: dict[str, object]
73
+ _environ: Mapping[str, str] = field(
74
+ default_factory=lambda: dict(os.environ), repr=False
75
+ )
76
+
77
+ def __post_init__(self) -> None:
78
+ self.path = self.path.expanduser().absolute()
79
+
80
+ def _setting(self, key: str, environment: str) -> str | None:
81
+ value: object = self._environ.get(environment, self.values.get(key))
82
+ if value is None:
83
+ return None
84
+ if not isinstance(value, str) or not value:
85
+ raise ConfigError(f"{key} must be a nonempty string")
86
+ return value
87
+
88
+ @property
89
+ def url(self) -> str | None:
90
+ value = self._setting("url", "TL_URL")
91
+ return validate_url(value) if value is not None else None
92
+
93
+ @property
94
+ def domain(self) -> str | None:
95
+ value = self._setting("domain", "TL_DOMAIN")
96
+ if value is not None and not is_domain(value):
97
+ raise ConfigError(
98
+ "domain must be a valid domain name of at most 256 characters"
99
+ )
100
+ return value
101
+
102
+ @property
103
+ def agent_id(self) -> str | None:
104
+ value = self._setting("agent_id", "TL_AGENT_ID")
105
+ if value is not None and not is_segment(value):
106
+ raise ConfigError(
107
+ "agent_id must be a topic segment of at most 128 characters"
108
+ )
109
+ return value
110
+
111
+ @property
112
+ def worker_label(self) -> str:
113
+ value = self._setting("worker_label", "TL_WORKER") or "cli"
114
+ if not is_worker_label(value):
115
+ raise ConfigError(
116
+ "worker_label must contain 1 to 256 letters, digits, ., _ or -"
117
+ )
118
+ return value
119
+
120
+ def token(self, admin: bool = False) -> str:
121
+ """Read an identity credential, or the environment-only admin token."""
122
+ environment = "TL_ADMIN_TOKEN" if admin else "TL_TOKEN"
123
+ if environment in self._environ:
124
+ return _token(self._environ[environment], environment)
125
+ if admin:
126
+ raise ConfigError("Set TL_ADMIN_TOKEN for identity administration")
127
+ table = self.values.get("token", {})
128
+ if not isinstance(table, dict):
129
+ raise ConfigError("token must be a TOML table")
130
+ token_table = cast(dict[str, object], table)
131
+ filename = token_table.get("file", "token")
132
+ if not isinstance(filename, str) or not filename:
133
+ raise ConfigError("token.file must be a nonempty path string")
134
+ path = Path(filename).expanduser()
135
+ if not path.is_absolute():
136
+ path = self.path.parent / path
137
+ try:
138
+ value = path.read_text(encoding="utf-8").strip()
139
+ except (OSError, UnicodeError):
140
+ raise ConfigError(
141
+ "Cannot read identity token; set TL_TOKEN or token.file"
142
+ ) from None
143
+ return _token(value, "token.file")
144
+
145
+
146
+ def load_config(
147
+ path: Path | str | None = None, *, environ: Mapping[str, str] | None = None
148
+ ) -> Config:
149
+ """Select an explicit path, TL_CONFIG, or the platform's user config."""
150
+ environment = dict(os.environ if environ is None else environ)
151
+ if path is None:
152
+ selected = environment.get("TL_CONFIG")
153
+ if selected is not None:
154
+ if not selected:
155
+ raise ConfigError("TL_CONFIG must be a nonempty path")
156
+ path = selected
157
+ else:
158
+ path = user_config_path("tasklease") / "config.toml"
159
+ if isinstance(path, str) and not path:
160
+ raise ConfigError("config path must be nonempty")
161
+ resolved = Path(path).expanduser().absolute()
162
+ return Config(resolved, _read_values(resolved), environment)
163
+
164
+
165
+ def save_deployment(
166
+ config: Config,
167
+ *,
168
+ url: str,
169
+ account_id: str,
170
+ name: str,
171
+ bucket: str,
172
+ r2_credentials_pending: bool | None = None,
173
+ ) -> None:
174
+ """Merge deployment settings with the latest file and atomically save it.
175
+
176
+ Environment overrides and credentials are never part of the serialized
177
+ settings. Rereading avoids erasing settings edited since load_config.
178
+ An omitted credential-pending flag preserves its latest saved value.
179
+ """
180
+ url = validate_url(url)
181
+ deployment = {"account_id": account_id, "name": name, "bucket": bucket}
182
+ if any(not isinstance(value, str) or not value for value in deployment.values()):
183
+ raise ConfigError(
184
+ "Deployment account_id, name and bucket must be nonempty strings"
185
+ )
186
+ values = _read_values(config.path)
187
+ existing = values.get("cloudflare", {})
188
+ if not isinstance(existing, dict):
189
+ raise ConfigError("cloudflare must be a TOML table")
190
+ cloudflare = cast(dict[str, object], existing).copy()
191
+ cloudflare.update(deployment)
192
+ if r2_credentials_pending is not None:
193
+ cloudflare["r2_credentials_pending"] = r2_credentials_pending
194
+ values.update(url=url, cloudflare=cloudflare)
195
+ try:
196
+ serialized = tomli_w.dumps(values)
197
+ except (TypeError, ValueError):
198
+ raise ConfigError(
199
+ "Configuration contains values that cannot be saved"
200
+ ) from None
201
+
202
+ try:
203
+ atomic_replace(config.path, serialized.encode("utf-8"))
204
+ except OSError:
205
+ raise ConfigError(f"Cannot save configuration at {config.path}") from None
206
+ config.values = values
tasklease/errors.py ADDED
@@ -0,0 +1,89 @@
1
+ """Controlled client, service and configuration failures."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import ClassVar
6
+
7
+
8
+ class TaskleaseError(Exception):
9
+ """Base class for tasklease failures that callers can handle."""
10
+
11
+
12
+ class APIError(TaskleaseError):
13
+ """A refused operation with a code from the wire protocol."""
14
+
15
+ code: ClassVar[str]
16
+ status_code: ClassVar[int]
17
+
18
+
19
+ class Invalid(APIError):
20
+ code = "invalid"
21
+ status_code = 400
22
+
23
+
24
+ class Unauthenticated(APIError):
25
+ code = "unauthenticated"
26
+ status_code = 401
27
+
28
+
29
+ class Forbidden(APIError):
30
+ code = "forbidden"
31
+ status_code = 403
32
+
33
+
34
+ class NotFound(APIError):
35
+ code = "not_found"
36
+ status_code = 404
37
+
38
+
39
+ class Empty(APIError):
40
+ code = "empty"
41
+ status_code = 404
42
+
43
+
44
+ class Exists(APIError):
45
+ code = "exists"
46
+ status_code = 409
47
+
48
+
49
+ class TooLarge(APIError):
50
+ code = "too_large"
51
+ status_code = 413
52
+
53
+
54
+ class TransportError(TaskleaseError):
55
+ """An unavailable service or uncertain network outcome.
56
+
57
+ A mutating request may already have taken effect. The caller must decide
58
+ whether a retry is appropriate for that operation and its live task ID.
59
+ """
60
+
61
+ def __init__(self, message: str, *, status_code: int | None = None) -> None:
62
+ super().__init__(message)
63
+ self.status_code = status_code
64
+
65
+
66
+ class ProtocolError(TaskleaseError):
67
+ """The service did not return a recognizable protocol envelope."""
68
+
69
+
70
+ class ConfigError(TaskleaseError, ValueError):
71
+ """Configuration is missing, unreadable or invalid."""
72
+
73
+
74
+ class StoreError(TaskleaseError):
75
+ """Local requester state is missing, unreadable or inconsistent."""
76
+
77
+
78
+ API_ERRORS: dict[str, type[APIError]] = {
79
+ error.code: error
80
+ for error in (
81
+ Invalid,
82
+ Unauthenticated,
83
+ Forbidden,
84
+ NotFound,
85
+ Empty,
86
+ Exists,
87
+ TooLarge,
88
+ )
89
+ }