Skip to content

feat(core): add Supabase client, Clerk auth, and HTTP client with typed deps [AYG-67]#2209

Closed
amostt wants to merge 5 commits intofastapi:masterfrom
Aygentic:amos/ayg-67-38-supabase-client-clerk-auth-http-client
Closed

feat(core): add Supabase client, Clerk auth, and HTTP client with typed deps [AYG-67]#2209
amostt wants to merge 5 commits intofastapi:masterfrom
Aygentic:amos/ayg-67-38-supabase-client-clerk-auth-http-client

Conversation

@amostt
Copy link

@amostt amostt commented Feb 27, 2026

Summary

  • Add Supabase client factory (create_supabase_client) and FastAPI dependency (get_supabase) from app.state
  • Add Clerk JWT authentication dependency (get_current_principal) with structured error codes: AUTH_MISSING_TOKEN, AUTH_EXPIRED_TOKEN, AUTH_INVALID_TOKEN
  • Add async HTTP client wrapper with retry on 502/503/504, exponential backoff, circuit breaker (5 failures/60s window), and X-Request-ID/X-Correlation-ID header propagation
  • Add typed FastAPI dependencies: SupabaseDep, PrincipalDep, HttpClientDep, RequestIdDep
  • Add lifespan context manager for Supabase + HttpClient init/teardown
  • Add session_id field to Principal model

Changes

Status File Description
A backend/app/core/supabase.py Supabase client factory + FastAPI dep
A backend/app/core/auth.py Clerk JWT auth with error mapping
A backend/app/core/http_client.py Async HTTP client: retry, circuit breaker, header propagation
A backend/tests/unit/test_supabase.py 4 unit tests
A backend/tests/unit/test_auth.py 12 unit tests
A backend/tests/unit/test_http_client.py 30 unit tests
M backend/app/api/deps.py Typed deps: SupabaseDep, PrincipalDep, HttpClientDep, RequestIdDep
M backend/app/main.py Lifespan for Supabase + HttpClient init/teardown
M backend/app/models/auth.py Added session_id: str to Principal
M backend/pyproject.toml Added supabase>=2.0.0, clerk-backend-api>=1.0.0
M backend/tests/unit/test_models.py Updated Principal tests for session_id

Review Summary

  • Critical: 0 (2 auto-fixed) | High: 0 (3 auto-fixed) | Medium: 10 | Low: 8
  • Tests: 115/115 passing (46 new + 69 existing)
  • Lint: Passing | Format: Passing

Test Plan

  • Unit tests for Supabase client (4 tests)
  • Unit tests for Clerk auth (12 tests)
  • Unit tests for HTTP client + circuit breaker (30 tests)
  • Updated Principal model tests (3 tests)
  • All 115 unit tests passing
  • Ruff lint + format clean

Fixes AYG-67

🤖 Generated with Claude Code by Aygentic

amostt and others added 5 commits February 27, 2026 03:54
@amostt
docs: add PRD for microservice-template-foundation
96fa33e
@amostt
chore: rename master branch to main and refresh project docs
0785188 
Rename default branch from master to main across all CI workflows,
documentation, and PRD. Also adds comprehensive project documentation
generated by the initialise skill (CLAUDE.md, docs/ structure).

🤖 Generated by Aygentic

Co-Authored-By: Aygentic <noreply@aygentic.com>
@amostt
feat(core): rewrite config, error handlers, and shared models [AYG-65] (
c10f1bf 
#1)

* feat(core): rewrite config, error handlers, and shared models [AYG-65]

- Replace PostgreSQL/SMTP settings with Supabase+Clerk env vars
- Add frozen Settings with production secret and CORS guards
- Create unified error response shape with global exception handlers
- Add shared Pydantic models: ErrorResponse, ValidationErrorResponse, PaginatedResponse, Principal

Fixes AYG-65

🤖 Generated by Aygentic

Co-Authored-By: Aygentic <noreply@aygentic.com>

* fix(core): untrack .env and guard conftest for migration [AYG-65]

- Remove .env from git tracking and add to .gitignore (SEC-001)
- Guard integration test conftest.py imports with try/except so unit
  tests run without --noconftest during the migration (FUNC-002)

Related to AYG-65

🤖 Generated by Aygentic

Co-Authored-By: Aygentic <noreply@aygentic.com>

* fix(tests): harden test isolation for template usage [AYG-65]

- Catch all exceptions (including ValidationError) in conftest guard so
  pytest doesn't crash when env vars are unset in a fresh template clone
- Explicitly delenv missing vars in test_missing_required_var_raises so
  the test is deterministic regardless of the caller's shell environment

Related to AYG-65

🤖 Generated by Aygentic

Co-Authored-By: Aygentic <noreply@aygentic.com>

* docs(project): update documentation before merge [skip ci]

Updated documentation based on AYG-65 code changes:
- setup.md: replaced PostgreSQL/SMTP/JWT env vars with Supabase/Clerk
- deployment/environments.md: updated all env tables and GitHub Secrets
- architecture/overview.md: added error handling framework, shared models, Clerk auth
- architecture/decisions/: new ADRs for error handling and models package
- api/overview.md: Clerk auth, standard error shape, paginated response pattern
- api/endpoints/login.md: deprecated (Clerk migration)
- api/endpoints/users.md + items.md: updated auth and error response docs
- data/models.md: new Shared Pydantic Models section
- testing/test-registry.md: +36 unit tests, closed config coverage gap

Related to AYG-65

🤖 Generated by Aygentic

Co-Authored-By: Aygentic <noreply@aygentic.com>

---------

Co-authored-by: Aygentic <noreply@aygentic.com>
@amostt
feat(core): add structured logging and request pipeline middleware [A…
f57968b 
…YG-66] (#2)

* feat(core): add structured logging and request pipeline middleware [AYG-66]

Add structlog-based structured logging (JSON/console modes) and request
pipeline middleware providing UUID v4 request IDs, correlation ID
propagation, security headers on all responses (including CORS preflight),
and status-based log levels (info/warning/error for 2xx/4xx/5xx).

- Create backend/app/core/logging.py: structlog configuration with
  JSON renderer (production) and ConsoleRenderer (local dev), base
  fields (timestamp, level, event, service, version, environment),
  contextvars integration for request-scoped fields
- Create backend/app/core/middleware.py: RequestPipelineMiddleware
  with request_id generation, X-Correlation-ID propagation, 6 security
  headers (X-Content-Type-Options, X-Frame-Options, X-XSS-Protection,
  Referrer-Policy, Permissions-Policy, HSTS production-only),
  X-Request-ID on every response including error and exception paths
- Wire into main.py with documented middleware ordering (outermost
  wraps CORSMiddleware so preflight OPTIONS get headers too)
- 32 new unit tests (6 logging + 26 middleware) covering CORS preflight
  header behavior, X-Request-ID on 4xx/5xx/exception paths, and
  negative tests proving Authorization/Cookie values never logged

Fixes AYG-66

🤖 Generated by Aygentic

Co-Authored-By: Aygentic <noreply@aygentic.com>

* docs(core): update architecture, test registry, and deployment docs for AYG-66 [skip ci]

Updated documentation based on structured logging and request pipeline middleware implementation.

Related to AYG-66

🤖 Generated by Aygentic

Co-Authored-By: Aygentic <noreply@aygentic.com>

---------

Co-authored-by: Aygentic <noreply@aygentic.com>
@amostt
feat(core): add Supabase client, Clerk auth, and HTTP client with typ…
e68ff9e 
…ed deps [AYG-67]

Implement the three core infrastructure dependencies for the microservice template:

- Supabase client: factory function + FastAPI dependency from app.state
- Clerk JWT auth: validate Bearer tokens, extract Principal with roles,
  map error reasons to structured error codes (AUTH_MISSING_TOKEN,
  AUTH_EXPIRED_TOKEN, AUTH_INVALID_TOKEN)
- HTTP client wrapper: async httpx with retry on 502/503/504,
  exponential backoff, circuit breaker (5 failures/60s window),
  X-Request-ID/X-Correlation-ID header propagation from structlog
- Typed FastAPI dependencies: SupabaseDep, PrincipalDep, HttpClientDep,
  RequestIdDep via Annotated[T, Depends()]
- Lifespan context manager: init Supabase + HttpClient at startup,
  close httpx pool on shutdown
- Added session_id field to Principal model

44 new unit tests (113 total), all passing.

Fixes AYG-67

🤖 Generated by Aygentic

Co-Authored-By: Aygentic <noreply@aygentic.com>
@amostt
Copy link
Author

amostt commented Feb 27, 2026

Opened against wrong repo by mistake — closing.

@amostt amostt closed this Feb 27, 2026
@amostt amostt deleted the amos/ayg-67-38-supabase-client-clerk-auth-http-client branch February 27, 2026 16:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@amostt