Implement spoe-auth relation interface library

[Copilot]

[!] Bootstrapped by Copilot

This PR only add the library implementation and tests. Logic for using the library and updating haproxy config will be shipped in a follow-up PR.

Applicable spec: https://discourse.charmhub.io/t/specification-isd257-haproxy-auth-proxy-using-spoe-auth-relation/19264

Overview

Implements the spoe-auth relation interface library to enable communication between haproxy-operator (Requirer) and SPOA authentication agents (Provider) for OIDC authentication offloading.

Rationale

HAProxy charm needs standardized interface to receive SPOE configuration from external authentication agents without hardcoding agent-specific details.

Library Changes

Usage example:

# Provider (SPOA agent)
from charms.haproxy.v0.spoe_auth import SpoeAuthProvider

self.spoe_auth = SpoeAuthProvider(self, relation_name="spoe-auth")
self.spoe_auth.provide_spoe_auth_requirements(
    spop_port=9000,
    oidc_callback_port=8080,
    event="on-http-request",
    var_authenticated="txn.authenticated",
    var_redirect_url="txn.redirect_url",
    cookie_name="auth_session",
    oidc_callback_hostname="auth.example.com"
)

# Requirer (HAProxy)
from charms.haproxy.v0.spoe_auth import SpoeAuthRequirer

self.spoe_auth = SpoeAuthRequirer(self, relation_name="spoe-auth")

Checklist

• The charm style guide was applied
• The contributing guide was applied
• The changes are compliant with ISD054 - Managing Charm Complexity
• The documentation for charmhub is updated
• A change artifact was added for user-relevant changes in docs/release-notes/artifacts.
• The PR is tagged with appropriate label (urgent, trivial, complex)
• The changelog is updated with user-relevant changes in the format of keep a changelog v1.1.0

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[copilot] Implement the spoe-auth Juju Relation Interface</issue_title>
<issue_description>### Enhancement Proposal

Goal: Implement the new spoe-auth relation interface library based on the provided design document (ISD257) to facilitate communication between the haproxy-operator (as the Requirer) and an external Stream Process Offloading Agent (SPOA) that handles OIDC authentication (as the Provider).

This library will enable the HAProxy charm to receive necessary SPOE configuration details from the authentication agent.

📌 Reference Documentation

The complete specification for this relation is detailed in:

Design Document: Specification (ISD257): Haproxy auth proxy using spoe-auth relation

🛠️ Implementation Details

The implementation must be structured as a standard Juju relation library, taking inspiration from existing libraries in lib/charms/haproxy/.

1. Relation Interface

Name: spoe-auth

Interface Type: Single-purpose relation designed for OIDC/Auth SPOA integration.

Limit: The relation is limited to one Provider application for the initial iteration.

2. Library Structure (lib/charms/haproxy/spoe_auth.py)

Both the Provider and Requirer classes should be implemented in a single library file.

Pydantic Validation: Use Pydantic models to define, parse, and validate the relation data exchanged. This ensures data integrity and provides clear error handling for missing or invalid data.

3. Data Model (Pydantic Base Model)

A Pydantic BaseModel should be created to represent the Provider's application data. This model will be used by both the Provider and Requirer.

Mandatory Provider Application Data Fields:

Attribute	Type	Description
spop_port	int	The port on the agent listening for SPOP. (Required)
oidc_callback_port	int	The port on the agent handling OIDC callbacks. (Required)
event	str	The event that triggers SPOE messages (e.g., on-http-request). (Required)
var_authenticated	str	Name of the variable set by the SPOE agent for auth status. (Required)
var_redirect_url	str	Name of the variable set by the SPOE agent for IDP redirect URL. (Required)
cookie_name	str	Name of the authentication cookie used by the SPOE agent. (Required)
oidc_callback_path	str	Path for OIDC callback. (Default: /oauth2/callback)
oidc_callback_hostname	str	The hostname HAProxy should route OIDC callbacks to. (Required)

Note: The library will be responsible for serializing this model into the Juju relation data (strings) and deserializing/validating it on the receiving end.

4. Provider Class (SpoeAuthProvider)

This library class will be used by the SPOE agent charm (the Provider).

Functionality:

Provide a method to set and automatically validate the application data using the Pydantic model.

This class will serialize the Pydantic model into the application data bucket.

5. Requirer Class (SpoeAuthRequirer)

This library class will be used by the haproxy-operator (the Requirer).

Functionality:

Provide a method to retrieve and parse the Provider's application data, validating it against the Pydantic model.

Expose the validated data via properties or a data object.

Provide methods to check if the relation is properly configured (is_available() or similar), which should return True only if the data is present and passes Pydantic validation.

✅ Deliverables

Create the new library file: lib/charms/haproxy/spoe_auth.py.

Implement the Pydantic data model, SpoeAuthProvider class, and SpoeAuthRequirer class within that file.

Include comprehensive docstrings and type hints for all classes, methods, and properties, respecting the existing coding style in the repository.

The resulting library should simplify the complex data exchange detailed in the ISD257 document into a single, validated, and easy-to-use Python module.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [copilot] Implement the spoe-auth Juju Relation Interface #228

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[arturo-seijas]

LGTM. Some minor nitpicks :)

[Thanhphan1147]

Published the lib beforehand to be able to start work on #232

[javierdelapuente]

looks good, a few comments

[Thanhphan1147]

closing this PR and moved the PR to charmlibs: canonical/charmlibs#252