pympacds-http 0.1.0__tar.gz

pympacds_http-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: pympacds-http
+Version: 0.1.0
+Summary: HTTP client service for pympacds
+Author-email: Oscar Diaz <odiaz@ieee.org>
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pympacds>=0.2.0
+Requires-Dist: aiohttp>=3.0
+
+# pympacds-http
+
+HTTP client service for [pympacds](https://github.com/dargor0/pympacds). Sends
+data over HTTP on behalf of other services and exposes it over D-Bus, with
+automatic retry and optional mutual TLS.
+
+## Features
+
+- Fire-and-forget D-Bus API: `send`, `download`, and `request` each return a
+  random request token immediately; the result is delivered asynchronously via
+  the `request_completed(token, result)` signal, so callers correlate a call
+  with its outcome by token.
+- A single pooled `aiohttp.ClientSession` (native asyncio, no thread
+  offloading), created at startup with no network I/O and closed on shutdown.
+- Automatic retry of transient failures (network error, timeout, HTTP 5xx)
+  with exponential backoff (`retries`, `retry_backoff_s`).
+- TLS verification control (`tls_verify`) plus mutual TLS via
+  `tls_certfile`/`tls_keyfile` (must be provided together).
+- `download` / `request` with a `download_path` write the response body
+  atomically to disk (temp file + rename) for binary/large downloads.
+- Runtime configuration: `[http]` keys are writable via the framework
+  `ConfigContract`.
+- Exports the framework `HealthContract` (always) and `ConfigContract`
+  (opt-in via `[dbus] contract_config = true`) alongside the HTTP contract.
+
+### Why aiohttp
+
+The service uses [aiohttp](https://docs.aiohttp.org/) because it is asyncio
+native: requests run directly on the framework's single event loop with no
+thread offloading. It is isolated in this service's own package, so the core
+`pympacds` framework keeps its zero-dependency property (the core's
+`httpconfprov` middleware continues to use the stdlib `urllib.request`).
+
+## Installation
+
+```bash
+pip install pympacds-http
+```
+
+## Configuration
+
+The service reads its parameters from the `[http]` INI section (see
+`config/http.ini.example`). Key options:
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `timeout_s` | `10` | Per-request timeout |
+| `retries` | `3` | Number of retry attempts |
+| `retry_backoff_s` | `1` | Initial backoff (exponential) between retries |
+| `tls_verify` | `true` | Verify TLS certificates |
+| `tls_certfile` / `tls_keyfile` | `""` | Client cert/key (PEM) for mutual TLS |
+| `max_redirects` | `5` | Maximum redirects to follow |
+| `default_url` | `""` | Target URL used by `send()` (empty = `send()` fails) |
+| `default_method` | `POST` | Default HTTP method used by `send()` |
+| `default_headers` | `""` | Default headers (JSON object) used by `send()` |
+
+Run with:
+
+```bash
+pympacds-http -c /etc/pympacds/http.ini
+```
+
+## D-Bus API
+
+Interface `org.pympacds.HTTP` at object path `/org/pympacds/http`:
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `send(payload)` | `send(s) -> s` | Send with default url/method/headers; returns a token |
+| `download(payload, download_path)` | `download(ss) -> s` | Like `send`, but saves the body to `download_path` |
+| `request(method, url, headers, body, download_path)` | `request(sssss) -> s` | Explicit request; empty `download_path` = return body |
+| `request_completed(token, result)` | signal `(ss)` | Emitted on completion; carries the token and JSON result |
+
+All sends are **fire-and-forget**: the method returns immediately with a
+randomized token, the request runs asynchronously, and `request_completed` is
+emitted with the full JSON outcome:
+
+```json
+{
+  "status_code": 200,
+  "url": "https://example.com/api",
+  "elapsed_ms": 123,
+  "body": "...",
+  "download_path": null,
+  "bytes_written": null,
+  "error": null
+}
+```
+
+The framework `HealthContract` (at `.../health`) and `ConfigContract`
+(`[dbus] contract_config = true`) are also exported.

pympacds_http-0.1.0/README.md

@@ -0,0 +1,91 @@
+# pympacds-http
+
+HTTP client service for [pympacds](https://github.com/dargor0/pympacds). Sends
+data over HTTP on behalf of other services and exposes it over D-Bus, with
+automatic retry and optional mutual TLS.
+
+## Features
+
+- Fire-and-forget D-Bus API: `send`, `download`, and `request` each return a
+  random request token immediately; the result is delivered asynchronously via
+  the `request_completed(token, result)` signal, so callers correlate a call
+  with its outcome by token.
+- A single pooled `aiohttp.ClientSession` (native asyncio, no thread
+  offloading), created at startup with no network I/O and closed on shutdown.
+- Automatic retry of transient failures (network error, timeout, HTTP 5xx)
+  with exponential backoff (`retries`, `retry_backoff_s`).
+- TLS verification control (`tls_verify`) plus mutual TLS via
+  `tls_certfile`/`tls_keyfile` (must be provided together).
+- `download` / `request` with a `download_path` write the response body
+  atomically to disk (temp file + rename) for binary/large downloads.
+- Runtime configuration: `[http]` keys are writable via the framework
+  `ConfigContract`.
+- Exports the framework `HealthContract` (always) and `ConfigContract`
+  (opt-in via `[dbus] contract_config = true`) alongside the HTTP contract.
+
+### Why aiohttp
+
+The service uses [aiohttp](https://docs.aiohttp.org/) because it is asyncio
+native: requests run directly on the framework's single event loop with no
+thread offloading. It is isolated in this service's own package, so the core
+`pympacds` framework keeps its zero-dependency property (the core's
+`httpconfprov` middleware continues to use the stdlib `urllib.request`).
+
+## Installation
+
+```bash
+pip install pympacds-http
+```
+
+## Configuration
+
+The service reads its parameters from the `[http]` INI section (see
+`config/http.ini.example`). Key options:
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `timeout_s` | `10` | Per-request timeout |
+| `retries` | `3` | Number of retry attempts |
+| `retry_backoff_s` | `1` | Initial backoff (exponential) between retries |
+| `tls_verify` | `true` | Verify TLS certificates |
+| `tls_certfile` / `tls_keyfile` | `""` | Client cert/key (PEM) for mutual TLS |
+| `max_redirects` | `5` | Maximum redirects to follow |
+| `default_url` | `""` | Target URL used by `send()` (empty = `send()` fails) |
+| `default_method` | `POST` | Default HTTP method used by `send()` |
+| `default_headers` | `""` | Default headers (JSON object) used by `send()` |
+
+Run with:
+
+```bash
+pympacds-http -c /etc/pympacds/http.ini
+```
+
+## D-Bus API
+
+Interface `org.pympacds.HTTP` at object path `/org/pympacds/http`:
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `send(payload)` | `send(s) -> s` | Send with default url/method/headers; returns a token |
+| `download(payload, download_path)` | `download(ss) -> s` | Like `send`, but saves the body to `download_path` |
+| `request(method, url, headers, body, download_path)` | `request(sssss) -> s` | Explicit request; empty `download_path` = return body |
+| `request_completed(token, result)` | signal `(ss)` | Emitted on completion; carries the token and JSON result |
+
+All sends are **fire-and-forget**: the method returns immediately with a
+randomized token, the request runs asynchronously, and `request_completed` is
+emitted with the full JSON outcome:
+
+```json
+{
+  "status_code": 200,
+  "url": "https://example.com/api",
+  "elapsed_ms": 123,
+  "body": "...",
+  "download_path": null,
+  "bytes_written": null,
+  "error": null
+}
+```
+
+The framework `HealthContract` (at `.../health`) and `ConfigContract`
+(`[dbus] contract_config = true`) are also exported.

pympacds_http-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pympacds-http"
+version = "0.1.0"
+description = "HTTP client service for pympacds"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    {name="Oscar Diaz", email="odiaz@ieee.org"}
+]
+dependencies = [
+    "pympacds>=0.2.0",
+    "aiohttp>=3.0",
+]
+
+[project.scripts]
+pympacds-http = "pympacds_http.service:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["src", "../../src"]
+addopts = [
+    "-v",
+    "--tb=short",
+    "--cov=pympacds_http",
+    "--cov-report=term-missing",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP"]
+
+# D-Bus type-signature string annotations ("s", "b", "ss", ...) are the
+# dbus-fast/dbus-next convention, not Python type references.
+[tool.ruff.lint.per-file-ignores]
+"src/pympacds_http/contracts.py" = ["F821", "F722"]
+
+[tool.mypy]
+python_version = "3.10"
+ignore_missing_imports = true
+mypy_path = ["../../src"]
+
+# The core framework has its own (pre-existing) typing debt ("object"-typed
+# D-Bus globals, D-Bus signature strings).  Treat it as Any rather than
+# re-checking it from the service.
+[[tool.mypy.overrides]]
+module = "pympacds"
+follow_imports = "silent"
+
+[[tool.mypy.overrides]]
+module = "pympacds.*"
+follow_imports = "silent"
+
+# D-Bus type-signature annotations ("s", "b", "ss", ...) are the dbus-fast/dbus-next
+# convention, not Python types; mypy tries to resolve them as forward references.
+[[tool.mypy.overrides]]
+module = "pympacds_http.contracts"
+disable_error_code = ["name-defined", "valid-type"]

pympacds_http-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pympacds_http-0.1.0/src/pympacds_http/__init__.py

@@ -0,0 +1,3 @@
+"""pympacds-http — HTTP client service for pympacds."""
+
+__version__ = "0.1.0"

pympacds_http-0.1.0/src/pympacds_http/contracts.py

@@ -0,0 +1,43 @@
+"""HTTP D-Bus contract (REQ-HTTP-004)."""
+
+from pympacds.contracts import ServiceContract, dbus_method, dbus_signal
+
+
+class HttpContract(ServiceContract):
+    """HTTP request interface."""
+
+    iface_name = "HTTP"
+    iface_version = "1.0.0"
+    iface_provides = ["http"]
+    iface_requires = ["network"]
+
+    def __init__(self, ifname: str, base):
+        super().__init__(ifname, base)
+        self._require(
+            "dbus_http_send",
+            "dbus_http_download",
+            "dbus_http_request",
+        )
+
+    @dbus_method()
+    def send(self, payload: "s") -> "s":
+        return self.base.dbus_http_send(payload)
+
+    @dbus_method()
+    def download(self, payload: "s", download_path: "s") -> "s":
+        return self.base.dbus_http_download(payload, download_path)
+
+    @dbus_method()
+    def request(
+        self,
+        method: "s",
+        url: "s",
+        headers: "s",
+        body: "s",
+        download_path: "s",
+    ) -> "s":
+        return self.base.dbus_http_request(method, url, headers, body, download_path)
+
+    @dbus_signal()
+    def request_completed(self, token: "s", result: "s") -> "ss":
+        return [token, result]