governed-http

A lightweight HTTP client with typed request/response contracts, request interception, and built-in request tracing.

It behaves like requests, but adds:

• Optional preflight checks before a request is sent
• Structured decision logging
• Pydantic-based request and response validation
• Dry-run mode (no network call)
• Pluggable transport for testing

Minimal dependencies: standard library + Pydantic.

Why use this?

Most HTTP clients simply send requests and return responses.

This client adds a control layer:

• Every request can be inspected before execution
• Calls can be blocked based on host or custom rules
• Each request records what was attempted and what happened
• Responses can be validated against typed models

Useful for:

• Restricting outbound API calls
• Enforcing allowed hosts
• Building typed API wrappers
• Testing external integrations deterministically
• Capturing structured request traces

Installation

pip install governed-http-sdk

Quick Example

from governed_http import Client

client = Client(
    base_url="https://api.example.com",
    allowed_hosts=["api.example.com"]
)

res = client.get("/status")
print(res.status_code)

Typed Operations

from pydantic import BaseModel
from governed_http import Client, Operation

class CreateThing(BaseModel):
    name: str

class Thing(BaseModel):
    id: int
    name: str

op = Operation(
    method="POST",
    path="/v1/things",
    request=CreateThing,
    response=Thing,
)

client = Client(
    base_url="https://api.example.com",
    allowed_hosts=["api.example.com"]
)

result: Thing = client.call(op, {"name": "example"})

The payload is validated before sending. The response is parsed into a typed model.

Dry Run (No Network)

preview = client.dry_run_request("GET", "/v1/things")
print(preview)

Returns:

• Final URL
• Headers
• Request body
• Preflight decision

Interceptors

Custom logic can be added before or after a request:

• Allow or deny outbound calls
• Modify headers
• Record additional metadata
• Enforce custom policy rules

Testing with Mock Transport

The built-in MockTransport allows deterministic testing without network access.

Summary

This package provides:

• A small, dependency-light HTTP client
• Typed request/response validation
• Optional outbound host restrictions
• Structured request tracing
• Pluggable transport for testing

It is designed for applications that need more control and visibility over outbound HTTP calls than a basic client provides.

Install (editable)

Push-Location artifact-verifier
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .
Pop-Location