osp-uio-integrations 0.1.0__py3-none-any.whl

osp_uio_integrations/__init__.py

@@ -0,0 +1,17 @@
+"""Shared integration clients for UiO-specific infrastructure services.
+
+This package provides reusable Python clients and small normalization helpers
+for external UiO systems such as MREG and Nivlheim. It exists to keep raw API
+glue in one place so providers and other callers do not duplicate auth,
+request/response handling, pagination, error mapping, or stable host and
+record normalization.
+
+It does not own provider workflow, approval policy, ownership decisions, or
+orchestrator/provider wire contracts.
+"""
+
+from .mreg import MregClient
+from .nivlheim import NivlheimClient
+from .version import __version__
+
+__all__ = ["MregClient", "NivlheimClient", "__version__"]

osp_uio_integrations/mreg/README.md

@@ -0,0 +1,131 @@
+# mreg — Package Guide
+
+The `osp_uio_integrations.mreg` package is a small synchronous Python client
+for UiO's MREG API. It owns transport, token-backed authentication, request
+metadata, light response normalization, and the explicit host/record APIs
+exposed through `MregClient`.
+
+It does not try to be a generic MREG framework, and it does not own provider
+workflow, orchestration policy, or CLI rendering concerns. The package exists
+to give other Python code a boring importable library surface for common MREG
+operations.
+
+## What Lives Here
+
+- `client.py` — HTTP transport boundary, token handling, one-shot `401`
+  retry, request metadata, compatibility fallback for legacy writes
+- `auth/` — login and token helpers
+- `exceptions.py` — stable exception taxonomy used across transport and domain
+  operations
+- `hosts/` — explicit host-facing API surface exposed as `client.hosts`
+
+## Public Surface
+
+Most callers should import from `osp_uio_integrations.mreg`, not from
+individual implementation modules.
+
+Primary entrypoints:
+
+- `MregClient`
+- `client.hosts`
+- `client.hosts.records`
+
+Stable supporting types:
+
+- enums such as `AddressFamily`, `SshfpAlgorithm`, `SshfpHashType`
+- exception types such as `RequestFailedError`, `ValidationError`,
+  `MutationStateUncertainError`
+- stable return-shape models re-exported from
+  `osp_uio_integrations.mreg.hosts` and
+  `osp_uio_integrations.mreg.hosts.records`
+
+Example:
+
+```python
+from osp_uio_integrations.mreg import MregClient, MutationStateUncertainError
+
+client = MregClient(base_url="https://mreg.example.test", token="token")
+
+try:
+    host = client.hosts.queries.get("example.uio.no")
+    record = client.hosts.records.ptr.add("example.uio.no", "192.0.2.10")
+finally:
+    client.close()
+```
+
+## Package Shape
+
+The package is deliberately explicit rather than generic.
+
+```text
+mreg/
+  client.py          transport + auth + request/response contract
+  exceptions.py      stable error taxonomy
+  auth/              login and token helpers
+  hosts/             host composition root and host sub-APIs
+    queries.py       host lookup + payload interpretation
+    lifecycle.py     create/delete
+    addressing.py    A/AAAA add/change/move/remove
+    contacts.py      host contact mutations
+    cnames.py        alias workflows
+    history.py       host history lookups
+    records/         host-owned RR modules under client.hosts.records
+```
+
+The important ownership rule is that `client.py` owns transport behavior,
+while `hosts/` owns endpoint-aware MREG business rules for the host domain.
+Models stay small data shapes; they do not perform I/O themselves.
+
+## Error Model
+
+The package uses a narrow exception taxonomy rather than exposing
+raw `httpx` or upstream-specific failures directly.
+
+- `RequestFailedError` means the request failed in the ordinary sense:
+  transport failure, non-success HTTP status, or another request-backed
+  problem where the library is not claiming partial mutation state
+- `ValidationError` means the library or MREG rejected the payload as invalid
+- `ResponseDecodeError` means MREG returned a success response the client
+  could not interpret into the promised shape
+- `MutationStateUncertainError` means a write likely reached MREG, but the
+  client could not safely confirm the resulting state
+
+That last exception is the important one for callers doing write workflows.
+MREG is not transactional. When a write succeeds upstream and follow-up
+verification fails, the library reports uncertainty explicitly instead of
+pretending it knows that nothing changed.
+
+For multi-step workflows such as address move or bulk record deletion,
+`MutationStateUncertainError` may include `completed_steps` and
+`remaining_steps` so callers can log what probably happened.
+
+## Design Boundaries
+
+The package does:
+
+- normalize request metadata such as `User-Agent` and `X-Correlation-ID`
+- keep a stable exception contract
+- port concrete host and RR workflows from `mreg-cli` into library-shaped
+  modules
+- add cheap local validations that clearly pay off
+
+The package does not:
+
+- implement transactional writes
+- implement rollback or retry frameworks
+- build a generic resource abstraction over all of MREG
+- duplicate all upstream semantic validation locally
+- own CLI prompts outside the optional auth prompt hook
+
+When in doubt, prefer explicit module-local logic over shared helper
+machinery.
+
+## Read Next
+
+- [__init__.py](__init__.py) — public import surface
+- [client.py](client.py) — transport contract
+- [hosts/__init__.py](hosts/__init__.py) — host-facing import surface
+- [hosts/records/__init__.py](hosts/records/__init__.py) — RR-facing import
+  surface
+- [docs/mreg-host-library-plan.md](../../../docs/mreg-host-library-plan.md) —
+  architectural background

osp_uio_integrations/mreg/__init__.py

@@ -0,0 +1,60 @@
+"""MREG client package.
+
+This package provides a small synchronous client for the UiO MREG API. It owns
+transport, token handling, and light response normalization for MREG-facing
+callers. The public surface exported here is the intended import root for most
+library users:
+
+- `MregClient` for transport and composed domain APIs
+- stable enums used at call boundaries
+- the small exception taxonomy callers are expected to catch
+
+It does not own orchestration policy, provider workflow, or command-line
+interaction beyond an optional credentials prompt hook. Concrete submodules
+under `osp_uio_integrations.mreg` remain implementation details unless they are
+re-exported here or documented as public elsewhere.
+"""
+
+from .client import MregClient
+from .enums import (
+    AddressFamily,
+    CompatibilityFallback,
+    RequestMethod,
+    SshfpAlgorithm,
+    SshfpHashType,
+    ValidationSource,
+)
+from .exceptions import (
+    AuthenticationFailedError,
+    AuthenticationRequiredError,
+    ConflictError,
+    ForbiddenError,
+    MregError,
+    MutationStateUncertainError,
+    MutationStep,
+    NotFoundError,
+    RequestFailedError,
+    ResponseDecodeError,
+    ValidationError,
+)
+
+__all__ = [
+    "AuthenticationFailedError",
+    "AuthenticationRequiredError",
+    "AddressFamily",
+    "ConflictError",
+    "ForbiddenError",
+    "CompatibilityFallback",
+    "MregClient",
+    "MregError",
+    "MutationStateUncertainError",
+    "MutationStep",
+    "NotFoundError",
+    "RequestMethod",
+    "RequestFailedError",
+    "ResponseDecodeError",
+    "SshfpAlgorithm",
+    "SshfpHashType",
+    "ValidationSource",
+    "ValidationError",
+]

osp_uio_integrations/mreg/auth/README.md

@@ -0,0 +1,199 @@
+# auth (MREG Authentication Helpers)
+
+The `auth` package owns the token-auth flow: a credentials value object,
+the token-auth POST exchange, an optional interactive prompt, and a token
+storage protocol with an in-memory default.
+
+The package exists so the transport client (`mreg/client.py`) can stay
+focused on HTTP behavior while the actual auth contract — request shape,
+status-to-exception mapping, prompt hook, persistence boundary — stays in
+one auditable place.
+
+The package owns:
+
+- the token-auth wire contract (`POST /api/token-auth/`, form body, JSON
+  token response)
+- mapping HTTP status to `AuthenticationFailedError`,
+  `RequestFailedError`, or `ResponseDecodeError`
+- the optional interactive prompt used when no token is cached
+- a tiny `TokenStore` protocol so callers can plug in their own
+  persistence (keyring, file, secret manager) without changing the client
+
+The package does not own:
+
+- session, cookie, or SSO flows — token-auth only
+- token refresh on the wire — `MregClient` performs the one-shot 401
+  retry by re-issuing login and replaying the request once
+- credential discovery — env-var, config-file, or vault lookups belong in
+  the calling application
+
+## What lives here
+
+- **`__init__.py`** — re-exports the small public surface.
+- **`login.py`** — `Credentials` value object and `login_for_token()`,
+  the only place that constructs the token-auth request and classifies
+  its responses.
+- **`tokens.py`** — `TokenStore` `Protocol` and `MemoryTokenStore`
+  default implementation.
+- **`interactive.py`** — `CredentialPrompt` `Protocol` and
+  `prompt_for_credentials`, the default stdin/getpass prompt used when
+  the client needs credentials and the caller has not supplied a hook.
+
+---
+
+## Layer guides
+
+### `login.py` — login_for_token
+
+```python
+def login_for_token(
+    client: httpx.Client,
+    *,
+    credentials: Credentials,
+    correlation_id: str | None = None,
+) -> str
+```
+
+`login_for_token` accepts a plain `httpx.Client` rather than a
+`MregClient` because the MREG transport boundary itself uses it during
+construction. It:
+
+- POSTs `username` / `password` as a form body to `/api/token-auth/`
+- forwards `X-Correlation-ID` when provided
+- maps `401`/`403` to `AuthenticationFailedError`
+- maps any other `>=400` to `RequestFailedError`
+- maps non-JSON or token-less success bodies to `ResponseDecodeError`
+- returns the issued token string on success
+
+`Credentials` is a frozen, slotted dataclass holding `username` and
+`password`. Treat it as a short-lived value object; do not log it.
+
+### `tokens.py` — TokenStore protocol
+
+```python
+class TokenStore(Protocol):
+    def load_token(self, *, base_url, username) -> str | None: ...
+    def save_token(self, *, base_url, username, token) -> None: ...
+    def clear_token(self, *, base_url, username) -> None: ...
+```
+
+The protocol is keyed on `(base_url, username)` so a single store can
+hold tokens for multiple MREG instances or multiple users. `username`
+may be `None` when the caller does not pin one.
+
+`MemoryTokenStore` is the default. It is suitable for tests and
+short-lived processes; long-lived tools should pass a custom
+implementation backed by their preferred secret store.
+
+### `interactive.py` — CredentialPrompt protocol
+
+```python
+class CredentialPrompt(Protocol):
+    def __call__(self, *, base_url, username: str | None) -> Credentials: ...
+```
+
+`prompt_for_credentials` is the default implementation. It uses `input()`
+for the username (when not supplied) and `getpass()` for the password.
+The protocol is what the client expects, so callers can plug in
+non-interactive credential providers (config-file lookups, secret
+manager fetches, test fakes) without touching `MregClient`.
+
+---
+
+## How `MregClient` uses these helpers
+
+`MregClient.__init__` accepts both a `credential_prompt` and a
+`token_store`. Each defaults to the helpers above:
+
+```python
+self._credential_prompt = credential_prompt or prompt_for_credentials
+self._token_store       = token_store or MemoryTokenStore()
+```
+
+The auth flow at request time is:
+
+1. If a token is already cached for `(base_url, username)`, reuse it.
+2. On `401` from a real request, drop the cached token and prompt the
+   `CredentialPrompt` for credentials.
+3. Call `login_for_token(...)`; persist the returned token through
+   `TokenStore.save_token(...)`.
+4. Replay the original request once with the new token. Any further
+   `401` is surfaced to the caller.
+
+The package never retries beyond that one-shot refresh. Repeated 401s
+are treated as configuration or credential problems and propagate as
+`AuthenticationFailedError`.
+
+---
+
+## Design recipes
+
+### Why a `Protocol` for `TokenStore` and `CredentialPrompt`
+
+Using `Protocol` (instead of an abstract base class) lets callers plug in
+keyring-backed storage, environment-driven credential providers, or test
+fakes without inheriting from anything in this package. `MregClient`
+depends on the shape, not the type.
+
+### Why credentials are a frozen dataclass, not raw strings
+
+`Credentials` keeps the username and password together at the call site,
+makes accidental mutation noisy, and gives type-checkers a stable type
+to reason about. It does not implement `__repr__` redaction; do not log
+instances.
+
+### Why login error mapping lives here
+
+Status-to-exception mapping for `/api/token-auth/` belongs next to the
+endpoint that defines it, not in transport. Keeping it here means
+`mreg/client.py` does not need to know the difference between a 401
+during login and a 401 during a normal data request.
+
+---
+
+## Design rules
+
+- **No retry policy in this package.** `login_for_token` issues exactly
+  one POST. Retries and the one-shot refresh dance live in the client.
+- **`TokenStore` keys are `(base_url, username)`.** Callers pin
+  `username` when they want per-user isolation; otherwise stores hold
+  one token per base URL.
+- **`prompt_for_credentials` is best-effort interactive.** It assumes a
+  TTY. Headless callers must inject their own `CredentialPrompt`
+  implementation.
+- **No HTTP session is shared between login and request.** The client
+  drives both, so this package does not assume anything about cookies
+  or persistent auth headers.
+
+---
+
+## Common issues
+
+- **`AuthenticationFailedError` on every request.** Either the cached
+  token is wrong (clear it via `TokenStore.clear_token(...)`) or the
+  account/password is invalid for the supplied `base_url`.
+- **Repeated prompts in a loop.** The one-shot refresh ran but the new
+  token was also rejected. Verify `Credentials.username` is the correct
+  identity for that `base_url`.
+- **`ResponseDecodeError: MREG login response did not include a token`.**
+  MREG returned 2xx but the body was empty or did not carry a `token`
+  field. Treat as a transient infrastructure problem; do not auto-retry.
+- **`RequestFailedError` during login.** Network or non-401/403 HTTP
+  failure. Inspect `status_code` and any `X-Request-Id` on the exception.
+
+---
+
+## Mini cheat sheet
+
+| I want to … | Use |
+|---|---|
+| Plug in custom credential lookup | Pass `credential_prompt=` to `MregClient` |
+| Plug in custom token persistence | Pass `token_store=` to `MregClient` |
+| Authenticate manually | `login_for_token(httpx_client, credentials=Credentials(...))` |
+| Drop a cached token | `token_store.clear_token(base_url=..., username=...)` |
+| Use a non-interactive flow | Implement `CredentialPrompt`; never call `prompt_for_credentials` |
+
+See [../README.md](../README.md) for the package-level surface,
+[../client.py](../client.py) for how the prompt and token store are wired
+into the transport, and [../exceptions.py](../exceptions.py) for the full
+exception taxonomy.

osp_uio_integrations/mreg/auth/__init__.py

@@ -0,0 +1,14 @@
+"""Authentication helpers for the MREG client."""
+
+from .interactive import CredentialPrompt, prompt_for_credentials
+from .login import Credentials, login_for_token
+from .tokens import MemoryTokenStore, TokenStore
+
+__all__ = [
+    "CredentialPrompt",
+    "Credentials",
+    "MemoryTokenStore",
+    "TokenStore",
+    "login_for_token",
+    "prompt_for_credentials",
+]

osp_uio_integrations/mreg/auth/interactive.py

@@ -0,0 +1,66 @@
+"""Interactive helpers for obtaining MREG credentials.
+
+The MREG client takes a :class:`CredentialPrompt` hook that it invokes
+when no usable token is cached and a fresh login is required. The default
+hook is the simple stdin/getpass prompt defined here, but the protocol is
+public so callers can plug in headless credential providers (config-file
+lookup, secret-manager fetch, test fakes) without touching the transport
+layer.
+
+This module owns only the interactive default and the protocol shape. It
+does not own token storage (see ``tokens.py``) or the token-auth wire
+exchange (see ``login.py``).
+"""
+
+from __future__ import annotations
+
+from getpass import getpass
+from typing import Protocol
+
+from .login import Credentials
+
+
+class CredentialPrompt(Protocol):
+    """Callable hook used by the MREG client to obtain login credentials.
+
+    Implementations may prompt the user, read from a config file, fetch
+    from a secret manager, or return canned credentials in tests. The
+    protocol intentionally mirrors a single call rather than a stateful
+    object so non-interactive providers stay trivial to implement.
+    """
+
+    def __call__(self, *, base_url: str, username: str | None) -> Credentials:
+        """Return :class:`Credentials` for the supplied MREG instance.
+
+        Args:
+            base_url: MREG base URL the credentials should authenticate
+                against. Useful for prompts that surface the target host
+                or for providers that pick a per-environment secret.
+            username: Username already known to the client, or ``None``
+                when the caller has not pinned one. Implementations may
+                reuse the value or prompt for a fresh username.
+        """
+
+
+def prompt_for_credentials(*, base_url: str, username: str | None) -> Credentials:
+    """Prompt the operator for an MREG username and password on stdin.
+
+    This is the default :class:`CredentialPrompt` used by ``MregClient``
+    when none is supplied. It assumes a real TTY: the username is read
+    from ``input()`` (when not already known) and the password is read
+    from ``getpass()`` so it does not echo. Headless callers should
+    replace this hook entirely rather than depending on terminal
+    behavior.
+
+    Args:
+        base_url: MREG base URL surfaced in the username prompt so the
+            operator can tell which instance is asking.
+        username: Username already known to the client, or ``None`` to
+            prompt for one.
+
+    Returns:
+        A :class:`Credentials` value object to feed into ``login_for_token``.
+    """
+    prompt_username = username or input(f"Username for {base_url}: ").strip()
+    password = getpass(f"Password for {prompt_username}: ")
+    return Credentials(username=prompt_username, password=password)

osp_uio_integrations/mreg/auth/login.py

@@ -0,0 +1,118 @@
+"""Token login helpers for the MREG client."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from ..enums import RequestMethod
+from ..exceptions import AuthenticationFailedError, RequestFailedError, ResponseDecodeError
+
+
+@dataclass(frozen=True, slots=True)
+class Credentials:
+    """Credentials used to authenticate against MREG."""
+
+    username: str
+    password: str
+
+
+def login_for_token(
+    client: httpx.Client,
+    *,
+    credentials: Credentials,
+    correlation_id: str | None = None,
+) -> str:
+    """Exchange username/password credentials for one MREG API token.
+
+    The transport client owns token lifecycle, but the actual token-auth
+    protocol is isolated here so the request shape and its error mapping stay
+    easy to audit. The function accepts a plain ``httpx.Client`` because it is
+    used by the MREG transport boundary itself, not by domain modules.
+
+    Args:
+        client: Configured ``httpx.Client`` used to reach the token-auth
+            endpoint.
+        credentials: Username/password pair to exchange for a token.
+        correlation_id: Optional correlation id propagated to the auth request
+            for traceability.
+
+    Returns:
+        Newly issued MREG API token.
+
+    Raises:
+        AuthenticationFailedError: MREG rejected the supplied credentials.
+        RequestFailedError: Network failure or unexpected upstream HTTP status
+            prevented successful login.
+        ResponseDecodeError: Login succeeded but the response body did not
+            contain a usable token.
+    """
+    endpoint = "/api/token-auth/"
+    try:
+        response = client.post(
+            endpoint,
+            data={
+                "username": credentials.username,
+                "password": credentials.password,
+            },
+            headers=_auth_headers(correlation_id),
+        )
+    except httpx.HTTPError as exc:
+        raise RequestFailedError(
+            "MREG login request failed",
+            method=RequestMethod.POST,
+            endpoint=endpoint,
+            correlation_id=correlation_id,
+        ) from exc
+
+    if response.status_code in (401, 403):
+        raise AuthenticationFailedError(
+            "MREG rejected the supplied credentials",
+            method=RequestMethod.POST,
+            status_code=response.status_code,
+            endpoint=endpoint,
+            request_id=response.headers.get("X-Request-Id"),
+            correlation_id=response.headers.get("X-Correlation-ID") or correlation_id,
+        )
+    if response.status_code >= 400:
+        raise RequestFailedError(
+            f"MREG login failed with status {response.status_code}",
+            method=RequestMethod.POST,
+            status_code=response.status_code,
+            endpoint=endpoint,
+            request_id=response.headers.get("X-Request-Id"),
+            correlation_id=response.headers.get("X-Correlation-ID") or correlation_id,
+        )
+
+    try:
+        payload: Any = response.json()
+    except ValueError as exc:
+        raise ResponseDecodeError(
+            "MREG login response was not valid JSON",
+            method=RequestMethod.POST,
+            status_code=response.status_code,
+            endpoint=endpoint,
+            request_id=response.headers.get("X-Request-Id"),
+            correlation_id=response.headers.get("X-Correlation-ID") or correlation_id,
+        ) from exc
+
+    token = payload.get("token") if isinstance(payload, dict) else None
+    if not isinstance(token, str) or not token:
+        raise ResponseDecodeError(
+            "MREG login response did not include a token",
+            method=RequestMethod.POST,
+            status_code=response.status_code,
+            endpoint=endpoint,
+            request_id=response.headers.get("X-Request-Id"),
+            correlation_id=response.headers.get("X-Correlation-ID") or correlation_id,
+        )
+    return token
+
+
+def _auth_headers(correlation_id: str | None) -> dict[str, str]:
+    """Build token-auth headers, forwarding a correlation id when available."""
+    if not correlation_id:
+        return {}
+    return {"X-Correlation-ID": correlation_id}

osp_uio_integrations/mreg/auth/tokens.py

@@ -0,0 +1,75 @@
+"""Token storage abstractions for the MREG client.
+
+The transport client never hardcodes how API tokens are persisted. Instead
+it depends on the small :class:`TokenStore` ``Protocol`` defined here, so
+callers can plug in keyring-backed storage, file-backed storage, secret
+managers, or test fakes without changing the client. The
+:class:`MemoryTokenStore` shipped here is the safe default for tests and
+short-lived processes.
+
+This module owns the persistence boundary contract and one in-memory
+implementation. It does not own credential collection (see
+``interactive.py``) or the token-auth wire flow (see ``login.py``).
+"""
+
+from __future__ import annotations
+
+from collections.abc import MutableMapping
+from typing import Protocol
+
+
+class TokenStore(Protocol):
+    """Persistence interface used by the MREG client to cache API tokens.
+
+    All operations are keyed on ``(base_url, username)`` so a single store
+    can hold tokens for multiple MREG instances and multiple identities at
+    the same time. ``username`` may be ``None`` when the calling code does
+    not pin a specific user identity to the cached token.
+    """
+
+    def load_token(self, *, base_url: str, username: str | None) -> str | None:
+        """Return a previously persisted token, or ``None`` if none is cached."""
+
+    def save_token(self, *, base_url: str, username: str | None, token: str) -> None:
+        """Persist ``token`` for the supplied ``base_url`` / ``username`` key."""
+
+    def clear_token(self, *, base_url: str, username: str | None) -> None:
+        """Drop any persisted token for the supplied key.
+
+        Called by the client when a cached token is rejected by MREG (for
+        example after a 401) so that the next request triggers a fresh
+        login instead of reusing the known-bad token.
+        """
+
+
+class MemoryTokenStore:
+    """Process-local in-memory implementation of :class:`TokenStore`.
+
+    Suitable for tests and short-lived CLI invocations. Long-running tools
+    should pass a custom store backed by their preferred secret manager so
+    tokens survive across processes and are not held in plain Python
+    memory longer than needed.
+    """
+
+    def __init__(self, initial: MutableMapping[tuple[str, str | None], str] | None = None) -> None:
+        """Create a store, optionally seeded with already-known tokens.
+
+        Args:
+            initial: Optional mapping of ``(base_url, username)`` to token
+                used to preload the store. Useful in tests that need to
+                exercise the cached-token path without going through a
+                real login.
+        """
+        self._tokens: dict[tuple[str, str | None], str] = dict(initial or {})
+
+    def load_token(self, *, base_url: str, username: str | None) -> str | None:
+        """Return the cached token for the key, or ``None`` if absent."""
+        return self._tokens.get((base_url, username))
+
+    def save_token(self, *, base_url: str, username: str | None, token: str) -> None:
+        """Replace any existing cached token for the supplied key."""
+        self._tokens[(base_url, username)] = token
+
+    def clear_token(self, *, base_url: str, username: str | None) -> None:
+        """Drop the cached token for the supplied key if one exists."""
+        self._tokens.pop((base_url, username), None)