Internal Audit API Client for Service-to-Service Communication

[nycomp]

Overview

Create an internal HTTP client for the Campus audit service that follows Campus API schema conventions. This client enables campus.auth and campus.api deployments to send trace spans to campus.audit via HTTP.

Background

The tracing middleware (issue #428) needs to send trace data to the audit service. Since the middleware runs in separate deployment processes (campus.auth, campus.api), it cannot import audit resources directly and must use HTTP.

Design

Follows campus-api-python structure with:

• ResourceCollection for collections (e.g., Traces)
• Nested classes for individual items (e.g., Traces.Trace)
• Standard verbs: new(), list(), search(), get()
• Bracket access for IDs: client.traces[trace_id]
• Property access for named sub-resources: client.traces[trace_id].spans
• Uses campus.common.http.DefaultClient for HTTP

Implementation

Files Created

• campus/audit/client/__init__.py - AuditClient entry point
• campus/audit/client/interface.py - ResourceRoot, ResourceCollection, Resource base classes
• campus/audit/client/v1/__init__.py - v1 API module
• campus/audit/client/v1/root.py - AuditRoot resource
• campus/audit/client/v1/traces.py - Traces, Trace, Spans, Span resources
• tests/unit/audit/test_client.py - Client initialization tests
• tests/unit/audit/test_interface.py - Base resource class tests
• tests/unit/audit/test_traces.py - Traces resource tests

API Usage

from campus.audit.client import AuditClient

client = AuditClient()

# Ingest spans
client.traces.new(span_data)           # Single
client.traces.new(s1, s2, s3)          # Batch

# List/search traces
client.traces.list(limit=10)
client.traces.search(path="/api/v1/users")

# Get trace tree
tree = client.traces[trace_id].get_tree()

# Get span
span = client.traces[trace_id].spans[span_id].get()

Related Issues

• Parent: Audit deployment #424 (Audit deployment)
• Part of: Audit Phase 4: Tracing Middleware #428 (Phase 4: Tracing Middleware)
• Depends on: Audit Phase 1: Models and Storage #425 (Models and Storage), Audit Phase 2: Resources Layer #426 (Resources Layer), Audit Phase 3: Routes and Authentication #427 (Routes and Authentication)

Acceptance Criteria

• Client follows Campus API schema conventions
• Supports all trace operations (ingest, list, search, get_tree, get_span)
• Environment-based URL resolution (development/testing/staging/production)
• Uses campus.common.http.DefaultClient for HTTP
• Proper error handling and logging
• Nested class structure matching campus-api-python
• Bracket access for IDs, property access for named resources
• Standard verbs (new(), list(), search(), get())

Testing

• Unit tests for client methods (test_client.py, test_interface.py, test_traces.py)
• Integration tests with real audit service
• Contract tests matching server-side API

[nycomp]

Required Tests for campus.audit.client

Test Structure

tests/unit/audit/
├── __init__.py
├── test_client.py           # AuditClient initialization, URL resolution
├── test_traces.py           # Traces resource methods
└── test_interface.py        # Resource base classes

tests/contract/
├── test_audit_client.py     # HTTP contract tests for client operations

1. Unit Tests (tests/unit/audit/test_client.py)

AuditClient Initialization

• test_client_initialization_with_env - Verify client reads CLIENT_ID/CLIENT_SECRET
• test_url_resolution_development - Verify Railway development URL
• test_url_resolution_testing - Verify localhost/current hostname
• test_url_resolution_staging - Verify staging URL
• test_url_resolution_production - Verify production URL
• test_url_relative_when_in_audit_deployment - Verify relative URL when DEPLOY=campus.audit
• test_traces_property_returns_traces_resource - Verify client.traces returns Traces instance

Client Singleton (middleware integration)

• test_get_audit_client_returns_singleton - Verify middleware uses same client instance
• test_client_lazy_initialization - Verify client created on first use

2. Unit Tests (tests/unit/audit/test_traces.py)

Traces Resource

• test_traces_path_has_trailing_slash - Verify path = "traces/"
• test_traces_make_path - Verify path construction
• test_traces_getitem_returns_trace_resource - Verify bracket access creates Trace
• test_traces_new_single_span - Verify new(span) calls POST with {"spans": [span]}
• test_traces_new_batch_spans - Verify new(s1, s2, s3) calls POST with all spans
• test_traces_list_with_defaults - Verify list() uses default params
• test_traces_list_with_params - Verify list(limit=10, since="...") includes params
• test_traces_search_with_filters - Verify search includes query params

Trace Resource (nested)

• test_trace_path_construction - Verify path includes trace_id
• test_trace_get_tree - Verify GET request to correct endpoint
• test_trace_spans_property_returns_spans_resource - Verify .spans returns Spans

Spans Resource (nested)

• test_spans_path_construction - Verify path includes "spans/"
• test_spans_list - Verify GET request
• test_spans_getitem_returns_span_resource - Verify bracket access

Span Resource (nested)

• test_span_path_construction - Verify path includes span_id
• test_span_get - Verify GET request

3. Unit Tests (tests/unit/audit/test_interface.py)

ResourceCollection

• test_resource_collection_path_must_have_trailing_slash - Verify validation
• test_resource_collection_make_path - Verify path construction
• test_resource_collection_client_propagation - Verify client from parent

Resource

• test_resource_path_construction - Verify path from parent + parts
• test_resource_client_propagation - Verify client from parent

4. Contract Tests (tests/contract/test_audit_client.py)

Following the pattern from test_auth_clients.py:

Authentication

• test_ingest_requires_auth - Verify 401 without credentials
• test_ingest_with_basic_auth - Verify 201 with valid Basic auth
• test_ingest_with_bearer_auth - Verify 201 with valid Bearer auth

Ingest (POST /audit/v1/traces/)

• test_ingest_single_span_returns_201 - Verify response format
• test_ingest_batch_spans_returns_201 - Verify multiple spans accepted
• test_ingest_missing_spans_field_returns_400 - Verify validation error
• test_ingest_invalid_span_returns_400 - Verify schema validation

List (GET /audit/v1/traces/)

• test_list_traces_requires_auth - Verify 401 without auth
• test_list_traces_returns_summaries - Verify response format
• test_list_with_limit_param - Verify limit works
• test_list_with_since_until_params - Verify time filters

Get Trace Tree (GET /audit/v1/traces/{trace_id}/)

• test_get_trace_requires_auth - Verify 401 without auth
• test_get_trace_returns_tree - Verify hierarchical structure
• test_get_missing_trace_returns_404 - Verify error handling

List Spans (GET /audit/v1/traces/{trace_id}/spans/)

• test_list_spans_requires_auth - Verify 401 without auth
• test_list_spans_returns_flat_list - Verify response format

Get Span (GET /audit/v1/traces/{trace_id}/spans/{span_id}/)

• test_get_span_requires_auth - Verify 401 without auth
• test_get_span_returns_full_details - Verify includes headers/bodies
• test_get_missing_span_returns_404 - Verify error handling

Search (GET /audit/v1/traces/search)

• test_search_requires_auth - Verify 401 without auth
• test_search_with_path_filter - Verify path filtering works
• test_search_with_status_filter - Verify status filtering works

Priority Order

1. Unit tests first - Fast, no external dependencies
2. Contract tests second - Requires full service stack
3. Integration tests - End-to-end with real HTTP

[nycomp]

Implemented and committed unit tests for the audit client:

• test_interface.py: Tests for base resource classes (ResourceRoot, ResourceCollection, Resource)

  • Path construction with URL prefixes
  • Client propagation from parent to child
  • make_path() and make_url() methods

• test_client.py: Tests for AuditClient initialization

  • Mock verification of _get_base_url() and DefaultClient calls

• test_traces.py: Tests for Traces resource methods

  • new() for single and batch span ingestion
  • list() and search() query methods
  • Bracket access for Trace resources
  • Property access for Spans sub-resource
  • get_tree() and get() methods

All 204 unit tests pass, including:

• 6 sanity checks
• 30 integration tests
• Type checks (pyright)

Changes pushed to feature/audit-phase4-middleware branch.