platform-fastapicommon 0.1.0__tar.gz

platform_fastapicommon-0.1.0/.dockerignore

@@ -0,0 +1,29 @@
+.git
+.github
+.claude
+.cursor
+.venv
+.env
+.env.*
+!.env-example
+logs
+*.log
+coverage.*
+.coverage
+htmlcov
+.pytest_cache
+.mypy_cache
+.ruff_cache
+__pycache__
+*.pyc
+dist
+build
+*.egg-info
+# test code and tooling config are not needed at build/runtime
+tests/
+*.md
+!README.md
+Makefile
+docker-compose.yml
+docker/prometheus/prometheus.yml
+docs/

platform_fastapicommon-0.1.0/.env-example

@@ -0,0 +1,33 @@
+# Copy to .env for local development: cp .env-example .env
+
+# --- Application (examples/fastapi_service) ---
+APP_NAME=platform-fastapicommon-example
+APP_ENV=dev
+APP_PORT=8080
+BUILD_VERSION=dev
+
+# --- OpenTelemetry ---
+# Set to reach the local otel-collector started by `make docker-up` (OTLP/gRPC).
+# Leave unset to record spans without exporting them.
+OTLP_ENDPOINT=localhost:4317
+ENABLE_TRACING=true
+ENABLE_METRICS=true
+
+# --- Local logs -> Loki (Promtail tails this file when using make docker-up) ---
+LOG_FILE=logs/app.log
+
+# --- Observability stack (Docker host port mappings) ---
+OTEL_COLLECTOR_GRPC_PORT=4317
+OTEL_COLLECTOR_HTTP_PORT=4318
+TEMPO_HTTP_PORT=3200
+LOKI_HTTP_PORT=3100
+PROMETHEUS_HTTP_PORT=9090
+GRAFANA_HTTP_PORT=3000
+GRAFANA_ADMIN_USER=admin
+GRAFANA_ADMIN_PASSWORD=admin
+
+# Prometheus scrapes the example app on the host, not in the compose network.
+PROMETHEUS_SCRAPE_TARGET=host.docker.internal:8080
+
+# --- Tooling ---
+PYTHON=python3

platform_fastapicommon-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,10 @@
+# Default: every file requires review from the platform team.
+# Replace @BCBP-SOLUTIONS-FZC-LLC/platform-team with your actual team slug.
+* @BCBP-SOLUTIONS-FZC-LLC/platform-team
+
+# Workflow and release automation changes require explicit sign-off.
+.github/workflows/ @BCBP-SOLUTIONS-FZC-LLC/platform-team
+.github/dependabot.yml @BCBP-SOLUTIONS-FZC-LLC/platform-team
+
+# Public API surface — extra scrutiny.
+src/fastapicommon/ @BCBP-SOLUTIONS-FZC-LLC/platform-team

platform_fastapicommon-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: Bug report
+about: Report a defect in fastapicommon middleware or helpers
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Description
+A clear description of the bug.
+
+## Library version
+`fastapicommon==X.Y.Z`
+
+## Python version
+`python --version` output
+
+## Steps to reproduce
+1.
+2.
+3.
+
+## Expected behaviour
+What you expected to happen.
+
+## Actual behaviour
+What actually happened. Include error messages, stack traces, or log output.
+
+## Minimal reproduction
+```python
+# paste the smallest Python snippet that triggers the bug
+```
+
+## Additional context
+Any other relevant context (OS, container environment, related issues).

platform_fastapicommon-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,28 @@
+---
+name: Feature request
+about: Propose a new middleware, helper, or enhancement
+title: '[FEAT] '
+labels: enhancement
+assignees: ''
+---
+
+## Problem / motivation
+What problem does this solve? Who is affected?
+
+## Proposed solution
+Describe the API or behaviour change you'd like.
+
+```python
+# Example usage of the proposed feature
+```
+
+## Alternatives considered
+Other approaches you evaluated and why you ruled them out.
+
+## Acceptance criteria
+- [ ]
+- [ ]
+- [ ]
+
+## Additional context
+Links to related issues, RFCs, or prior art.

platform_fastapicommon-0.1.0/.github/SECURITY.md

@@ -0,0 +1,32 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 0.x     | ✅ Active |
+
+Older major versions are not patched. Upgrade to the latest 0.x release.
+
+## Reporting a Vulnerability
+
+**Do not open a public GitHub issue for security vulnerabilities.**
+
+Email: vijay@bcbpsolutions.com
+
+Include in your report:
+- Description of the vulnerability and affected component
+- Steps to reproduce
+- Potential impact (data exposure, privilege escalation, DoS, etc.)
+- Suggested fix or patch (if any)
+
+### Response timeline
+
+| Step | Target |
+|------|--------|
+| Initial acknowledgement | 48 hours |
+| Severity assessment | 5 business days |
+| Patch release (critical/high) | 14 days |
+| Public disclosure | After patch ships |
+
+We follow responsible disclosure. We will credit reporters in the release notes unless anonymity is requested.

platform_fastapicommon-0.1.0/.github/dependabot.yml

@@ -0,0 +1,22 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    labels: [dependencies, python]
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    labels: [dependencies, github-actions]
+
+  - package-ecosystem: docker
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    labels: [dependencies, docker]

platform_fastapicommon-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,59 @@
+## Description
+Provide a clear description of the changes.
+
+---
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactor
+- [ ] Documentation
+- [ ] Test
+- [ ] Breaking change
+
+---
+
+## Testing
+- [ ] Unit tests added/updated
+- [ ] All tests passing (`make test`)
+- [ ] Manual testing performed (if required)
+
+---
+
+## Checklist
+
+### Code Quality
+- [ ] Code is properly formatted (`make format` — ruff format + black)
+- [ ] Linting passed (`make lint` — ruff)
+- [ ] Type checking passed (`make lint` — mypy --strict)
+- [ ] No debug logs / commented code
+
+---
+
+### Observability (IMPORTANT for your system)
+- [ ] Logs include `request_id` / `correlation_id` (via `fastapicommon.logging.get_logger`, not stdlib `logging`)
+- [ ] Errors use a `PlatformException` subclass, not a bare `HTTPException`
+- [ ] Middleware ordering preserved if middleware changed (see `ARCHITECTURE.md#execution-model`)
+
+---
+
+### Security
+- [ ] No secrets hardcoded
+- [ ] Input validation handled
+- [ ] RBAC (`RequireRole` / `RequireAnyRole` / `RequireAllRoles`) checked (if endpoint changes)
+
+---
+
+### Documentation
+- [ ] README updated (if needed)
+- [ ] `ARCHITECTURE.md` / ADRs updated (if a cross-cutting standard changed)
+
+---
+
+## 🔗 Related Issue
+Closes #<issue-id>
+
+---
+
+## Deployment Notes
+Mention anything important for deployment.

platform_fastapicommon-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,334 @@
+# CI for https://github.com/BCBP-SOLUTIONS-FZC-LLC/platform-fastapicommon
+name: CI
+
+"on":
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    name: Validate
+    uses: ./.github/workflows/validate.yml
+
+  coverage:
+    name: Coverage (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    needs: validate
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12', '3.13', '3.14']
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dependencies
+        run: pip install -e ".[dev,grpc,examples]"
+
+      - name: Test with coverage (>=90% required, enforced by pyproject.toml)
+        run: pytest
+
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: coverage-report-py${{ matrix.python-version }}
+          path: coverage.xml
+          if-no-files-found: ignore
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    needs: coverage
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+          cache: pip
+
+      - name: Build wheel + sdist
+        run: |
+          pip install build
+          python -m build
+
+      - name: Verify build artifacts
+        run: ls dist/*.whl dist/*.tar.gz
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: fastapicommon-dist
+          path: dist/
+          if-no-files-found: error
+
+  lint-dockerfile:
+    name: Lint Dockerfile
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Run hadolint
+        uses: hadolint/hadolint-action@v3.3.0
+        with:
+          dockerfile: Dockerfile
+          failure-threshold: warning
+
+  build-image:
+    name: Build image (cache)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      # Booting buildx pulls the moby/buildkit image from Docker Hub, which occasionally
+      # times out on shared GitHub-hosted runner IPs ("context deadline exceeded") — a
+      # known transient flake, not a config problem. Retry once with the same action
+      # before failing the job.
+      - name: Set up Docker Buildx
+        id: buildx
+        continue-on-error: true
+        uses: docker/setup-buildx-action@v4
+
+      - name: Set up Docker Buildx (retry)
+        if: steps.buildx.outcome == 'failure'
+        uses: docker/setup-buildx-action@v4
+
+      - name: Build (no push)
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile
+          push: false
+          tags: platform-fastapicommon-example:ci
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  trivy-scan:
+    name: Trivy CVE scan
+    runs-on: ubuntu-latest
+    needs: build-image
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      # Booting buildx pulls the moby/buildkit image from Docker Hub, which occasionally
+      # times out on shared GitHub-hosted runner IPs ("context deadline exceeded") — a
+      # known transient flake, not a config problem. Retry once with the same action
+      # before failing the job.
+      - name: Set up Docker Buildx
+        id: buildx
+        continue-on-error: true
+        uses: docker/setup-buildx-action@v4
+
+      - name: Set up Docker Buildx (retry)
+        if: steps.buildx.outcome == 'failure'
+        uses: docker/setup-buildx-action@v4
+
+      # Rebuilds against the GHA cache populated by "Build image (cache)" — fast, and
+      # keeps this job self-contained (no cross-job image tarball transfer needed).
+      - name: Build image (load, cached)
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile
+          push: false
+          load: true
+          tags: platform-fastapicommon-example:ci
+          cache-from: type=gha
+
+      - name: Run Trivy vulnerability scan
+        uses: aquasecurity/trivy-action@v0.36.0
+        with:
+          image-ref: platform-fastapicommon-example:ci
+          format: table
+          severity: HIGH,CRITICAL
+          ignore-unfixed: true
+          exit-code: '1'
+          scanners: vuln
+
+  smoke-tests:
+    name: Smoke tests
+    runs-on: ubuntu-latest
+    needs: build-image
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      # Booting buildx pulls the moby/buildkit image from Docker Hub, which occasionally
+      # times out on shared GitHub-hosted runner IPs ("context deadline exceeded") — a
+      # known transient flake, not a config problem. Retry once with the same action
+      # before failing the job.
+      - name: Set up Docker Buildx
+        id: buildx
+        continue-on-error: true
+        uses: docker/setup-buildx-action@v4
+
+      - name: Set up Docker Buildx (retry)
+        if: steps.buildx.outcome == 'failure'
+        uses: docker/setup-buildx-action@v4
+
+      - name: Build image (load, cached)
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile
+          push: false
+          load: true
+          tags: platform-fastapicommon-example:ci
+          cache-from: type=gha
+
+      - name: Run container
+        run: docker run -d --name smoke-test -p 8080:8080 platform-fastapicommon-example:ci
+
+      - name: Wait for health check
+        run: |
+          for i in $(seq 1 30); do
+            if curl -fsS http://localhost:8080/health >/dev/null 2>&1; then
+              echo "healthy after ${i}s"
+              exit 0
+            fi
+            sleep 1
+          done
+          echo "Service did not become healthy in time" >&2
+          docker logs smoke-test
+          exit 1
+
+      - name: Smoke test endpoints
+        run: |
+          set -euo pipefail
+          curl -fsS http://localhost:8080/health | grep -q '"status":"ok"'
+          curl -fsS http://localhost:8080/ready | grep -q '"status":"ok"'
+          curl -fsS http://localhost:8080/metrics | grep -q 'http_requests_total'
+          curl -fsS http://localhost:8080/widgets/me | grep -q '"user_id":null'
+          echo "All smoke checks passed"
+
+      - name: Container logs
+        if: always()
+        run: docker logs smoke-test || true
+
+      - name: Stop container
+        if: always()
+        run: docker rm -f smoke-test || true
+
+  docker:
+    name: Docker image (example service)
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.event_name == 'push'
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Docker metadata
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ghcr.io/bcbp-solutions-fzc-llc/platform-fastapicommon
+          tags: |
+            type=ref,event=branch
+            type=sha,prefix=sha-,format=short
+
+      # Booting buildx pulls the moby/buildkit image from Docker Hub, which occasionally
+      # times out on shared GitHub-hosted runner IPs ("context deadline exceeded") — a
+      # known transient flake, not a config problem. Retry once with the same action
+      # before failing the job.
+      - name: Set up Docker Buildx
+        id: buildx
+        continue-on-error: true
+        uses: docker/setup-buildx-action@v4
+
+      - name: Set up Docker Buildx (retry)
+        if: steps.buildx.outcome == 'failure'
+        uses: docker/setup-buildx-action@v4
+
+      - name: Build and push image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          build-args: BUILD_VERSION=dev-${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  pr-summary:
+    name: PR summary
+    runs-on: ubuntu-latest
+    needs: [validate, build-image, lint-dockerfile, trivy-scan, smoke-tests]
+    if: always() && github.event_name == 'pull_request'
+    permissions:
+      pull-requests: write
+    steps:
+      - name: Post summary comment
+        uses: actions/github-script@v9
+        with:
+          script: |
+            const results = {
+              'Validate (Quality + Test)': '${{ needs.validate.result }}',
+              'Build image (cache)': '${{ needs.build-image.result }}',
+              'Lint Dockerfile': '${{ needs.lint-dockerfile.result }}',
+              'Trivy CVE scan': '${{ needs.trivy-scan.result }}',
+              'Smoke tests': '${{ needs.smoke-tests.result }}',
+            };
+            const icon = (r) => (r === 'success' ? '✅' : r === 'skipped' ? '⏭️' : '❌');
+            const rows = Object.entries(results)
+              .map(([name, result]) => `| ${name} | ${icon(result)} ${result} |`)
+              .join('\n');
+            const body = [
+              '### CI summary',
+              '',
+              '| Check | Result |',
+              '|---|---|',
+              rows,
+            ].join('\n');
+
+            const marker = '<!-- pr-summary-bot -->';
+            const fullBody = `${marker}\n${body}`;
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+            const existing = comments.find((c) => c.body.includes(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body: fullBody,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body: fullBody,
+              });
+            }

platform_fastapicommon-0.1.0/.github/workflows/quality.yml

@@ -0,0 +1,54 @@
+# Reusable workflow — called by validate.yml's "Quality" job. Its job id ("quality")
+# combines with the calling chain to produce the "Validate / Quality / quality" required
+# status check.
+# Runs: checkout → Python setup → install → pip check → format check → ruff → mypy → pip-audit
+name: Quality Check
+
+"on":
+  workflow_call:
+    inputs:
+      ref:
+        description: 'Git ref to check out (leave empty to use the caller ref)'
+        type: string
+        required: false
+        default: ''
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          ref: ${{ inputs.ref || github.ref }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+          cache: pip
+
+      - name: Install dependencies
+        run: pip install -e ".[dev,grpc,examples]"
+
+      - name: Verify dependency resolution
+        run: pip check
+
+      - name: Format check (ruff format + black --check)
+        run: |
+          ruff format --check src tests examples
+          black --check src tests examples
+
+      - name: Lint (ruff)
+        run: ruff check src tests examples
+
+      - name: Type check (mypy --strict)
+        run: mypy
+
+      - name: Vulnerability check (pip-audit)
+        run: |
+          pip install pip-audit
+          pip-audit