e407f4bc55
* feat: add OAuth extension hooks for MCP authentication Add extension points in core that allow cloud extensions to support OAuth 2.1 (RFC 9728 / RFC 7591) for MCP server authentication: - HttpExtension.get_root_router() for well-known endpoint mounting - AuthenticationError.headers for WWW-Authenticate propagation - MCP middleware forwards auth error headers to clients Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: document get_root_router and AuthenticationError.headers Add documentation for the new extension points introduced in the OAuth extension hooks commit. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Remove OAuth-specific wording from extension docs Make the AuthenticationError headers example generic instead of OAuth-specific, since these are general-purpose extension hooks. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
101 lines
3.3 KiB
Python
101 lines
3.3 KiB
Python
"""
|
|
HTTP Extension for adding custom endpoints to the Hindsight API.
|
|
|
|
This extension allows adding custom HTTP endpoints under the /ext/ path prefix.
|
|
The extension provides a FastAPI router that is mounted on the main application.
|
|
"""
|
|
|
|
from abc import ABC, abstractmethod
|
|
from typing import TYPE_CHECKING
|
|
|
|
from fastapi import APIRouter
|
|
|
|
from hindsight_api.extensions.base import Extension
|
|
|
|
if TYPE_CHECKING:
|
|
from hindsight_api import MemoryEngine
|
|
|
|
|
|
class HttpExtension(Extension, ABC):
|
|
"""
|
|
Base class for HTTP extensions that add custom API endpoints.
|
|
|
|
HTTP extensions provide a FastAPI router that gets mounted under /ext/.
|
|
The extension has full control over the routes, request/response models, and handlers.
|
|
|
|
Example:
|
|
```python
|
|
from fastapi import APIRouter
|
|
from hindsight_api.extensions import HttpExtension
|
|
|
|
class MyHttpExtension(HttpExtension):
|
|
def get_router(self, memory: MemoryEngine) -> APIRouter:
|
|
router = APIRouter()
|
|
|
|
@router.get("/hello")
|
|
async def hello():
|
|
return {"message": "Hello from extension!"}
|
|
|
|
@router.post("/custom/{bank_id}/action")
|
|
async def custom_action(bank_id: str):
|
|
# Access memory engine for database operations
|
|
pool = await memory._get_pool()
|
|
# ... custom logic
|
|
return {"status": "ok"}
|
|
|
|
return router
|
|
```
|
|
|
|
The routes will be available at:
|
|
- GET /ext/hello
|
|
- POST /ext/custom/{bank_id}/action
|
|
|
|
Configuration via environment variables:
|
|
HINDSIGHT_API_HTTP_EXTENSION=mypackage.ext:MyHttpExtension
|
|
HINDSIGHT_API_HTTP_SOME_CONFIG=value
|
|
|
|
The extension receives config: {"some_config": "value"}
|
|
"""
|
|
|
|
@abstractmethod
|
|
def get_router(self, memory: "MemoryEngine") -> APIRouter:
|
|
"""
|
|
Return a FastAPI router with custom endpoints.
|
|
|
|
The router will be mounted at /ext/ on the main application.
|
|
All routes defined in the router will be prefixed with /ext/.
|
|
|
|
Args:
|
|
memory: The MemoryEngine instance for database access and core operations.
|
|
Use this to access the connection pool, run queries, or call
|
|
memory operations like retain, recall, etc.
|
|
|
|
Returns:
|
|
A FastAPI APIRouter with the custom endpoints defined.
|
|
|
|
Example:
|
|
```python
|
|
def get_router(self, memory: MemoryEngine) -> APIRouter:
|
|
router = APIRouter(tags=["My Extension"])
|
|
|
|
@router.get("/status")
|
|
async def status():
|
|
health = await memory.health_check()
|
|
return {"extension": "healthy", "memory": health}
|
|
|
|
return router
|
|
```
|
|
"""
|
|
pass
|
|
|
|
def get_root_router(self, memory: "MemoryEngine") -> APIRouter | None:
|
|
"""
|
|
Return a FastAPI router with endpoints mounted at the app root.
|
|
|
|
Unlike get_router() which is mounted at /ext/, this router is mounted
|
|
directly on the application root. Use for well-known endpoints or other
|
|
paths that must be at specific locations.
|
|
|
|
Returns None by default (no root routes). Override to provide root-level routes.
|
|
"""
|
|
return None
|