croniq-runner 0.1.0__tar.gz

croniq_runner-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+# Build / distribution
+build/
+dist/
+*.egg-info/
+
+# Caches
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Runtime artefacts
+*.pyc

croniq_runner-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to the Python runner SDK are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+the package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - Unreleased
+
+### Added
+
+- Initial release of `croniq-runner` for Python 3.11+.
+- Async-first runner (`Runner.run`) over `httpx.AsyncClient`.
+- Pydantic v2 DTOs mirroring `openapi.yaml` snake_case wire format.
+- Streaming `LogWriter` backed by a bounded `asyncio.Queue` with batching
+  (32 events / 200 ms / max 100 per POST) and drain-before-ack guarantee.
+- Server-side cancellation via `PollResponse.cancel` honoured per-execution.
+- Lease-renewal heartbeat at `renew_interval` while a handler is in flight.
+- Self-registration via `POST /v1/jobs/register` for handlers declared with
+  a `schedule=` argument.
+- Authentication: `Authorization: ApiKey <key>` (preferred) or
+  `Authorization: Bearer <token>`.
+- Conformance binding under `tests/conformance/` driving the language-agnostic
+  YAML suite at [`sdks/conformance/cases/`](../conformance/cases) — one pytest
+  per case, runs against `pytest-httpserver`.
+- Optional OpenTelemetry tracing via the `croniq-runner[otel]` extra; spans
+  emitted around each execution when `opentelemetry-api` is importable.

croniq_runner-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: croniq-runner
+Version: 0.1.0
+Summary: Async Python runner SDK for Croniq — distributed job scheduling that just works.
+Project-URL: Homepage, https://github.com/nuetzliches/croniq
+Project-URL: Repository, https://github.com/nuetzliches/croniq
+Project-URL: Issues, https://github.com/nuetzliches/croniq/issues
+Project-URL: Documentation, https://github.com/nuetzliches/croniq/blob/main/sdks/python/README.md
+Author: Croniq Contributors
+License-Expression: MIT OR Apache-2.0
+Keywords: async,cron,croniq,runner,scheduler
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.6
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-httpserver>=1.1; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.24; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.24; extra == 'otel'
+Description-Content-Type: text/markdown
+
+# Croniq Runner SDK for Python
+
+[![PyPI](https://img.shields.io/pypi/v/croniq-runner.svg)](https://pypi.org/project/croniq-runner/)
+[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](#license)
+
+Build job execution runners for [Croniq](https://github.com/nuetzliches/croniq) in async Python. The SDK polls a Croniq server for work, dispatches your handlers, streams structured logs back, and reports completion — idiomatic `asyncio` + `httpx` + Pydantic v2.
+
+## Install
+
+```sh
+pip install croniq-runner
+# Optional: OpenTelemetry tracing
+pip install "croniq-runner[otel]"
+```
+
+Python 3.11+ required (`asyncio.TaskGroup`, `tomllib`).
+
+## Quick start
+
+```python
+import asyncio
+from croniq_runner import Runner, RunnerOptions
+
+async def hello(ctx):
+    ctx.logger.info("hello from %s (attempt %d)", ctx.job_key, ctx.attempt)
+    await ctx.log("emitting a structured event", fields={"customer": "acme"})
+
+async def main():
+    runner = Runner(RunnerOptions(
+        server_url="http://localhost:4000",
+        api_key="croniq_...",
+        capabilities=["billing"],
+        tags=["lang=python", "env=dev"],
+        max_inflight=5,
+    ))
+    runner.add_handler("hello:world", hello)
+    await runner.run()
+
+asyncio.run(main())
+```
+
+Stop the runner with `Ctrl-C` or by calling `runner.request_drain()` from
+another coroutine — in-flight handlers get up to `drain_timeout_ms` to finish
+before the loop returns.
+
+## Features
+
+- **`asyncio`-first** — every public coroutine returns awaitably; no sync surface.
+- **Pydantic v2 DTOs** mirroring `openapi.yaml` snake_case wire format.
+- **Two-tier logging**:
+  - `ctx.logger` — standard `logging.Logger` scoped with `execution_id`, `job_key`, `runner_id`, `attempt`.
+  - `ctx.log_writer` — streaming channel backed by a bounded `asyncio.Queue` with batching (32 events / 200 ms / max 100 per POST), drained before the ack.
+- **Server-side cancellation** — `PollResponse.cancel` is honoured via `ctx.cancellation` (an `asyncio.Event`). Handlers should `await ctx.cancellation.wait()` between checkpoints, or just use `await asyncio.sleep(...)` — the runner cancels the underlying task when the event fires.
+- **Lease renewal** — periodic `POST /v1/work/renew` heartbeat for each in-flight execution.
+- **Self-registration** — pass `schedule="5m"` to `add_handler` and the runner POSTs to `/v1/jobs/register` on startup.
+- **OpenTelemetry** — opt-in via the `[otel]` extra; spans wrap each handler invocation when `opentelemetry-api` is importable. Zero dependency otherwise.
+
+## Capabilities vs Tags
+
+A common pitfall: **don't put implementation details into capabilities**. Capabilities drive server-side job routing (`require`/`prefer` in the Croniqfile). Tags are filter-only — they show up in the UI and operational views but don't influence routing.
+
+| Good capability | Bad capability |
+|---|---|
+| `billing`, `reporting`, `gpu`, `sandboxed` | `python`, `linux-x64`, `dotnet` |
+
+If your runner is Python-based, that belongs in **tags** (`lang=python`, `platform=linux-x64`), not capabilities — so a future Rust- or .NET-runner with the same business capabilities can take over without rewriting Croniqfile entries.
+
+## Handler API
+
+A handler is any `async def fn(ctx: ExecutionContext) -> None`. The `ctx`
+exposes:
+
+| Attribute | Meaning |
+|-----------|---------|
+| `execution_id` | Server-assigned execution identifier |
+| `job_key` | E.g. `"billing:invoice"` |
+| `attempt` | 1-based attempt counter (incremented on retry) |
+| `metadata` | Raw `dict` from the server (job-specific schema) |
+| `timeout` | `datetime.timedelta` declared by the server |
+| `runner_id`, `runner_tags` | This runner's identity |
+| `cancellation` | `asyncio.Event` — fires on host shutdown or server-initiated cancel |
+| `logger` | `logging.Logger` pre-scoped with execution identifiers |
+| `log_writer` | Streaming `LogWriter` (created lazily on first access) |
+
+Two ways to control the ack failure message:
+
+```python
+from croniq_runner import HandlerError
+
+async def my_handler(ctx):
+    if not data_available():
+        raise HandlerError("upstream feed unavailable")  # ack.error = "upstream feed unavailable"
+```
+
+Any other exception's `str(exc)` is forwarded as the error message.
+
+## Configuration
+
+| Option | Default | Meaning |
+|--------|---------|---------|
+| `server_url` | `http://localhost:4000` | Croniq server base URL |
+| `runner_id` | resolved at start | Stable runner identifier — see resolution order in `_identity.py` |
+| `api_key` / `bearer_token` | `None` | Auth header (`ApiKey` preferred when both set) |
+| `capabilities` | `[]` | Capabilities advertised to the server |
+| `tags` | `[]` | Free-form `key=value` tags |
+| `max_inflight` | `5` | Concurrent in-flight executions |
+| `poll_timeout_ms` | `35_000` | Per-request long-poll timeout |
+| `renew_interval_ms` | `15_000` | Lease-renewal heartbeat interval |
+| `drain_timeout_ms` | `30_000` | Wait budget for handlers on shutdown |
+| `poll_retry_delay_ms` | `5_000` | Back-off after a failed poll |
+| `capacity_backoff_ms` | `500` | Idle delay at `max_inflight` |
+| `log_writer` | `LogWriterOptions()` | Streaming-log tunables |
+
+## Streaming logs example
+
+```python
+from croniq_runner import LogLevel
+
+async def long_job(ctx):
+    async with ctx.log_writer as writer:  # type: ignore[reportInvalidUsage]
+        async for line in slow_generator():
+            await writer.write(line, level=LogLevel.INFO)
+```
+
+You don't actually need `async with` — the runner drains the writer before
+the ack regardless. Calling `aclose()` yourself just lets you control *when*
+the drain happens (e.g. before a downstream API call that should see the
+events first).
+
+## Conformance suite
+
+The Python binding for the [language-agnostic conformance
+suite](../conformance/README.md) lives under `tests/conformance/`. Every
+case is one `pytest` parameter; run them with:
+
+```sh
+pip install -e ".[dev]"
+pytest tests/conformance
+```
+
+The cases live at `sdks/conformance/cases/*.yaml` and are loaded by file —
+adding a new YAML automatically adds a new test.
+
+## Development
+
+```sh
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev,otel]"
+ruff check .
+mypy
+pytest
+```
+
+## Releasing
+
+Releases run via [`.github/workflows/python-sdk-release.yml`](../../.github/workflows/python-sdk-release.yml) and upload to PyPI through Trusted Publishing (OIDC — no API token in the repo).
+
+1. Bump `version = "X.Y.Z"` in [`pyproject.toml`](pyproject.toml).
+2. Add a `## [X.Y.Z]` section to [`CHANGELOG.md`](CHANGELOG.md).
+3. Commit, push to `main`.
+4. Tag and push:
+   ```sh
+   git tag python-sdk-vX.Y.Z
+   git push origin python-sdk-vX.Y.Z
+   ```
+5. The workflow builds, verifies the tag matches `pyproject.toml`, publishes to PyPI, then attaches the wheel + sdist to a GitHub Release.
+
+One-time PyPI setup (project owner): add a Pending Publisher on [pypi.org](https://pypi.org/manage/account/publishing/) with project `croniq-runner`, owner `nuetzliches`, repository `croniq`, workflow `python-sdk-release.yml`, environment `pypi`.
+
+## License
+
+Dual-licensed under MIT or Apache-2.0, matching the rest of the Croniq
+repository.

croniq_runner-0.1.0/README.md

@@ -0,0 +1,173 @@
+# Croniq Runner SDK for Python
+
+[![PyPI](https://img.shields.io/pypi/v/croniq-runner.svg)](https://pypi.org/project/croniq-runner/)
+[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](#license)
+
+Build job execution runners for [Croniq](https://github.com/nuetzliches/croniq) in async Python. The SDK polls a Croniq server for work, dispatches your handlers, streams structured logs back, and reports completion — idiomatic `asyncio` + `httpx` + Pydantic v2.
+
+## Install
+
+```sh
+pip install croniq-runner
+# Optional: OpenTelemetry tracing
+pip install "croniq-runner[otel]"
+```
+
+Python 3.11+ required (`asyncio.TaskGroup`, `tomllib`).
+
+## Quick start
+
+```python
+import asyncio
+from croniq_runner import Runner, RunnerOptions
+
+async def hello(ctx):
+    ctx.logger.info("hello from %s (attempt %d)", ctx.job_key, ctx.attempt)
+    await ctx.log("emitting a structured event", fields={"customer": "acme"})
+
+async def main():
+    runner = Runner(RunnerOptions(
+        server_url="http://localhost:4000",
+        api_key="croniq_...",
+        capabilities=["billing"],
+        tags=["lang=python", "env=dev"],
+        max_inflight=5,
+    ))
+    runner.add_handler("hello:world", hello)
+    await runner.run()
+
+asyncio.run(main())
+```
+
+Stop the runner with `Ctrl-C` or by calling `runner.request_drain()` from
+another coroutine — in-flight handlers get up to `drain_timeout_ms` to finish
+before the loop returns.
+
+## Features
+
+- **`asyncio`-first** — every public coroutine returns awaitably; no sync surface.
+- **Pydantic v2 DTOs** mirroring `openapi.yaml` snake_case wire format.
+- **Two-tier logging**:
+  - `ctx.logger` — standard `logging.Logger` scoped with `execution_id`, `job_key`, `runner_id`, `attempt`.
+  - `ctx.log_writer` — streaming channel backed by a bounded `asyncio.Queue` with batching (32 events / 200 ms / max 100 per POST), drained before the ack.
+- **Server-side cancellation** — `PollResponse.cancel` is honoured via `ctx.cancellation` (an `asyncio.Event`). Handlers should `await ctx.cancellation.wait()` between checkpoints, or just use `await asyncio.sleep(...)` — the runner cancels the underlying task when the event fires.
+- **Lease renewal** — periodic `POST /v1/work/renew` heartbeat for each in-flight execution.
+- **Self-registration** — pass `schedule="5m"` to `add_handler` and the runner POSTs to `/v1/jobs/register` on startup.
+- **OpenTelemetry** — opt-in via the `[otel]` extra; spans wrap each handler invocation when `opentelemetry-api` is importable. Zero dependency otherwise.
+
+## Capabilities vs Tags
+
+A common pitfall: **don't put implementation details into capabilities**. Capabilities drive server-side job routing (`require`/`prefer` in the Croniqfile). Tags are filter-only — they show up in the UI and operational views but don't influence routing.
+
+| Good capability | Bad capability |
+|---|---|
+| `billing`, `reporting`, `gpu`, `sandboxed` | `python`, `linux-x64`, `dotnet` |
+
+If your runner is Python-based, that belongs in **tags** (`lang=python`, `platform=linux-x64`), not capabilities — so a future Rust- or .NET-runner with the same business capabilities can take over without rewriting Croniqfile entries.
+
+## Handler API
+
+A handler is any `async def fn(ctx: ExecutionContext) -> None`. The `ctx`
+exposes:
+
+| Attribute | Meaning |
+|-----------|---------|
+| `execution_id` | Server-assigned execution identifier |
+| `job_key` | E.g. `"billing:invoice"` |
+| `attempt` | 1-based attempt counter (incremented on retry) |
+| `metadata` | Raw `dict` from the server (job-specific schema) |
+| `timeout` | `datetime.timedelta` declared by the server |
+| `runner_id`, `runner_tags` | This runner's identity |
+| `cancellation` | `asyncio.Event` — fires on host shutdown or server-initiated cancel |
+| `logger` | `logging.Logger` pre-scoped with execution identifiers |
+| `log_writer` | Streaming `LogWriter` (created lazily on first access) |
+
+Two ways to control the ack failure message:
+
+```python
+from croniq_runner import HandlerError
+
+async def my_handler(ctx):
+    if not data_available():
+        raise HandlerError("upstream feed unavailable")  # ack.error = "upstream feed unavailable"
+```
+
+Any other exception's `str(exc)` is forwarded as the error message.
+
+## Configuration
+
+| Option | Default | Meaning |
+|--------|---------|---------|
+| `server_url` | `http://localhost:4000` | Croniq server base URL |
+| `runner_id` | resolved at start | Stable runner identifier — see resolution order in `_identity.py` |
+| `api_key` / `bearer_token` | `None` | Auth header (`ApiKey` preferred when both set) |
+| `capabilities` | `[]` | Capabilities advertised to the server |
+| `tags` | `[]` | Free-form `key=value` tags |
+| `max_inflight` | `5` | Concurrent in-flight executions |
+| `poll_timeout_ms` | `35_000` | Per-request long-poll timeout |
+| `renew_interval_ms` | `15_000` | Lease-renewal heartbeat interval |
+| `drain_timeout_ms` | `30_000` | Wait budget for handlers on shutdown |
+| `poll_retry_delay_ms` | `5_000` | Back-off after a failed poll |
+| `capacity_backoff_ms` | `500` | Idle delay at `max_inflight` |
+| `log_writer` | `LogWriterOptions()` | Streaming-log tunables |
+
+## Streaming logs example
+
+```python
+from croniq_runner import LogLevel
+
+async def long_job(ctx):
+    async with ctx.log_writer as writer:  # type: ignore[reportInvalidUsage]
+        async for line in slow_generator():
+            await writer.write(line, level=LogLevel.INFO)
+```
+
+You don't actually need `async with` — the runner drains the writer before
+the ack regardless. Calling `aclose()` yourself just lets you control *when*
+the drain happens (e.g. before a downstream API call that should see the
+events first).
+
+## Conformance suite
+
+The Python binding for the [language-agnostic conformance
+suite](../conformance/README.md) lives under `tests/conformance/`. Every
+case is one `pytest` parameter; run them with:
+
+```sh
+pip install -e ".[dev]"
+pytest tests/conformance
+```
+
+The cases live at `sdks/conformance/cases/*.yaml` and are loaded by file —
+adding a new YAML automatically adds a new test.
+
+## Development
+
+```sh
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev,otel]"
+ruff check .
+mypy
+pytest
+```
+
+## Releasing
+
+Releases run via [`.github/workflows/python-sdk-release.yml`](../../.github/workflows/python-sdk-release.yml) and upload to PyPI through Trusted Publishing (OIDC — no API token in the repo).
+
+1. Bump `version = "X.Y.Z"` in [`pyproject.toml`](pyproject.toml).
+2. Add a `## [X.Y.Z]` section to [`CHANGELOG.md`](CHANGELOG.md).
+3. Commit, push to `main`.
+4. Tag and push:
+   ```sh
+   git tag python-sdk-vX.Y.Z
+   git push origin python-sdk-vX.Y.Z
+   ```
+5. The workflow builds, verifies the tag matches `pyproject.toml`, publishes to PyPI, then attaches the wheel + sdist to a GitHub Release.
+
+One-time PyPI setup (project owner): add a Pending Publisher on [pypi.org](https://pypi.org/manage/account/publishing/) with project `croniq-runner`, owner `nuetzliches`, repository `croniq`, workflow `python-sdk-release.yml`, environment `pypi`.
+
+## License
+
+Dual-licensed under MIT or Apache-2.0, matching the rest of the Croniq
+repository.

croniq_runner-0.1.0/pyproject.toml

@@ -0,0 +1,96 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "croniq-runner"
+version = "0.1.0"
+description = "Async Python runner SDK for Croniq — distributed job scheduling that just works."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT OR Apache-2.0"
+authors = [{ name = "Croniq Contributors" }]
+keywords = ["croniq", "cron", "scheduler", "runner", "async"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Distributed Computing",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.6",
+]
+
+[project.optional-dependencies]
+otel = ["opentelemetry-api>=1.24", "opentelemetry-sdk>=1.24"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-httpserver>=1.1",
+    "pyyaml>=6.0",
+    "ruff>=0.6",
+    "mypy>=1.10",
+    "types-PyYAML",
+]
+
+[project.urls]
+Homepage = "https://github.com/nuetzliches/croniq"
+Repository = "https://github.com/nuetzliches/croniq"
+Issues = "https://github.com/nuetzliches/croniq/issues"
+Documentation = "https://github.com/nuetzliches/croniq/blob/main/sdks/python/README.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/croniq_runner"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/croniq_runner", "README.md", "CHANGELOG.md", "pyproject.toml"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+# Pragmatic default: pyflakes + pycodestyle + isort + bugbear + simplify.
+# Add rule families piecemeal — broad selects produce noise that drowns
+# real findings on the first run.
+select = ["E", "F", "I", "B", "SIM", "UP", "W"]
+ignore = [
+    "E501",  # line length: tracked by formatter, not linter
+    "B008",  # function call in argument default (httpx clients are fine)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["B011"]  # asserts in tests are fine
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+disallow_untyped_decorators = false  # pytest fixtures
+files = ["src/croniq_runner"]
+
+[[tool.mypy.overrides]]
+module = ["pytest_httpserver.*", "yaml.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+filterwarnings = [
+    "error",
+    # opentelemetry-api on Python 3.11 calls importlib.metadata.entry_points().values()
+    # at import time, which trips a DeprecationWarning fixed upstream in 3.12. The
+    # warning is harmless and out of our control — let it through so the OTel extra
+    # remains usable on the minimum supported Python.
+    "ignore:SelectableGroups dict interface is deprecated:DeprecationWarning",
+]
+addopts = "-ra --strict-markers --strict-config"

croniq_runner-0.1.0/src/croniq_runner/__init__.py

@@ -0,0 +1,48 @@
+"""Async Python runner SDK for Croniq.
+
+See https://github.com/nuetzliches/croniq for the server, OpenAPI spec, and
+SDKs in other languages.
+
+Public surface — every other symbol is an implementation detail and may move
+without a major-version bump:
+
+    Runner          — the poll/dispatch/ack loop
+    RunnerOptions   — runner configuration
+    ExecutionContext— handed to each handler
+    LogLevel        — string enum mirroring the server's log-level set
+    LogWriter       — streaming log channel (use via `ExecutionContext.log_writer`)
+    WorkEvent       — structured log event for `LogWriter.write`
+    HandlerError    — handler raises this to control the failure message
+
+Quick start::
+
+    from croniq_runner import Runner, RunnerOptions
+
+    async def hello(ctx):
+        ctx.logger.info("hello from %s", ctx.job_key)
+
+    runner = Runner(RunnerOptions(server_url="http://localhost:4000",
+                                   api_key="croniq_..."))
+    runner.add_handler("hello:world", hello)
+    await runner.run()
+"""
+
+from croniq_runner._context import ExecutionContext
+from croniq_runner._errors import HandlerError
+from croniq_runner._log_writer import LogLevel, LogWriter
+from croniq_runner._options import LogWriterOptions, RunnerOptions
+from croniq_runner._protocol import WorkEvent
+from croniq_runner._runner import Runner
+
+__all__ = [
+    "ExecutionContext",
+    "HandlerError",
+    "LogLevel",
+    "LogWriter",
+    "LogWriterOptions",
+    "Runner",
+    "RunnerOptions",
+    "WorkEvent",
+]
+
+__version__ = "0.1.0"

croniq_runner-0.1.0/src/croniq_runner/_client.py

@@ -0,0 +1,119 @@
+"""HTTP client over the Croniq Runner API.
+
+Wraps ``httpx.AsyncClient`` with snake_case JSON encoding and auth header
+injection. Per-request timeouts (notably for the long-poll on
+``/v1/work/poll``) are explicit on each call so the client-level timeout can
+stay generous.
+"""
+
+from __future__ import annotations
+
+import logging
+from types import TracebackType
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from croniq_runner._options import RunnerOptions
+from croniq_runner._protocol import (
+    AckRequest,
+    PollRequest,
+    PollResponse,
+    RegisterJobRequest,
+    RegisterJobResponse,
+    RenewRequest,
+    WorkEvent,
+)
+
+_log = logging.getLogger("croniq_runner.client")
+
+
+class CroniqClient:
+    """Async wire client. Owns the underlying :class:`httpx.AsyncClient`."""
+
+    def __init__(self, options: RunnerOptions, *, http: httpx.AsyncClient | None = None) -> None:
+        self._options = options
+        # 35 s long-poll plus a small head-room; per-call timeouts override.
+        default_timeout = httpx.Timeout(
+            connect=10.0,
+            read=40.0,
+            write=10.0,
+            pool=10.0,
+        )
+        self._http = http or httpx.AsyncClient(
+            base_url=options.server_url.rstrip("/"),
+            timeout=default_timeout,
+            headers=self._auth_headers(),
+        )
+        self._owns_client = http is None
+
+    @staticmethod
+    def _dump(payload: Any) -> dict[str, Any]:
+        """Pydantic dump matching the server's snake_case + omit-None convention."""
+        return payload.model_dump(mode="json", exclude_none=True)  # type: ignore[no-any-return]
+
+    def _auth_headers(self) -> dict[str, str]:
+        if self._options.api_key:
+            return {"Authorization": f"ApiKey {self._options.api_key}"}
+        if self._options.bearer_token:
+            return {"Authorization": f"Bearer {self._options.bearer_token}"}
+        return {}
+
+    async def __aenter__(self) -> CroniqClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._http.aclose()
+
+    async def poll(self, request: PollRequest, *, timeout_ms: int) -> PollResponse:
+        # Long-poll: the server may hold the connection for up to ~poll_timeout
+        # before returning an empty body. Allow a small read head-room so a
+        # graceful 200 doesn't race the client-side timeout.
+        timeout = httpx.Timeout(
+            connect=10.0,
+            read=timeout_ms / 1000.0 + 5.0,
+            write=10.0,
+            pool=10.0,
+        )
+        resp = await self._http.post("/v1/work/poll", json=self._dump(request), timeout=timeout)
+        resp.raise_for_status()
+        return PollResponse.model_validate(resp.json())
+
+    async def ack(self, request: AckRequest) -> None:
+        resp = await self._http.post("/v1/work/ack", json=self._dump(request))
+        resp.raise_for_status()
+
+    async def renew(self, request: RenewRequest) -> None:
+        resp = await self._http.post("/v1/work/renew", json=self._dump(request))
+        resp.raise_for_status()
+
+    async def push_events(self, execution_id: str, events: list[WorkEvent]) -> None:
+        if not events:
+            return
+        body = [self._dump(ev) for ev in events]
+        path = f"/v1/work/{quote(execution_id, safe='')}/events"
+        resp = await self._http.post(path, json=body)
+        resp.raise_for_status()
+
+    async def register_job(self, request: RegisterJobRequest) -> RegisterJobResponse | None:
+        resp = await self._http.post("/v1/jobs/register", json=self._dump(request))
+        resp.raise_for_status()
+        # Some server versions return 200 with no body; treat empty as None.
+        if not resp.content:
+            return None
+        try:
+            return RegisterJobResponse.model_validate(resp.json())
+        except ValueError:
+            # Body wasn't JSON / didn't match — non-fatal, we already got the 2xx.
+            _log.debug("register_job: unexpected response body (%s)", resp.text[:200])
+            return None