osp-uio-integrations

Shared Python integration package for UiO-specific infrastructure systems such as LDAP, MREG, and Nivlheim.

This repository is the concrete API-glue layer for external UiO systems. It is meant to keep authentication, request/response handling, error mapping, and small normalization helpers in one place so providers and transitional orchestrator code do not duplicate that plumbing.

Maintainer-facing boundaries and invariants live in each integration package's module documentation.

Scope

• Reusable Python clients for UiO infrastructure services
• Shared transport/auth/session glue
• API-specific response parsing and error translation
• Small stable normalized helper types where duplication would otherwise grow

Current focus

The LDAP integration owns the reusable UiO directory boundary shared by Python services and CLIs:

• service and end-user bind flows, including UiO's people/system user-DN fallback
• bounded ldap3 connect and receive timeouts
• safe equality and wildcard filter composition plus raw RFC 4515 filters
• user, people, host, organization, netgroup, and filegroup lookup
• automount lookup with the legacy one-hop LDAP indirection behavior
• normalized membership fields where the legacy CLI already established a useful output contract
• stable exceptions and password-safe reproduction commands for diagnostics

The Siteadmin integration owns the current netgroup-to-contact mapping read:

• anonymous, explicit-token, and managed username/password authentication
• bounded token refresh using Siteadmin's expires_at
• strict all-or-nothing validation of the grouped current-mapping response
• deterministic relation normalization that preserves multiple primary contacts
• stable request failures with Siteadmin error and request metadata
• public grouped contact-to-host lookup for provider inventory authorization

Caching, fixtures, snapshots, and ownership decisions remain caller policy.

The opt-in canonical package supplies comparison records for infrastructure facts without erasing their source:

• separate CanonicalHost and host-scoped CanonicalNetwork observations
• pure MREG, LDAP, and Nivlheim adapters with source-shaped raw snapshots
• explicit observed-field tracking so unknown differs from observed-empty
• exact-host grouping and diffs that do not choose authority or guess aliases

The MREG integration is a small synchronous library with:

• explicit transport and auth handling
• optional interactive login for token bootstrap
• request metadata headers such as User-Agent and X-Correlation-ID
• a host-focused surface covering queries, lifecycle, history, addressing, contacts, CNAMEs, and explicit DNS record modules
• host-policy role/atom helpers, including batched role lookup for many hosts
• VLAN host membership lookup with optional host-policy enrichment that avoids per-host API calls
• room to grow into further MREG areas without flattening everything into one module

For concrete usage examples and a translation table from supported mreg-cli commands to this library API, see docs/mreg-cli-command-map.md.

Non-goals

• Provider workflow or execution logic
• Ownership, approval, or placement policy
• Orchestrator/provider wire contracts
• Provider-specific planning decisions

Install

pip install osp-uio-integrations

Development

env -u VIRTUAL_ENV uv sync --extra dev
hatch shell
hatch run dev:check
hatch run dev:build
hatch run dev:verify

Release

See docs/release.md for the manual tag and publish flow.

Create and push the annotated release tag from the checked-in release notes:

hatch run dev:tag-push