Nest Engineering Docs
Handler

Local development

Run, debug, and test Handler locally

Prerequisites

  • uv and Python 3.13.
  • GCP credentials with access to Spanner, Cloud Tasks, and Secret Manager.
  • PartnerCreds service reachable (or mocked) for partner tokens.

Required environment

export GCP_PROJECT_ID="..."
export SPANNER_INSTANCE_ID="..."
export SPANNER_DATABASE_ID="..."
export BUBBLE_INVOICES_ENDPOINT="https://api.bubble.example/invoices"
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

Local settings file

Create services/handler/.env for local overrides:

DEBUG=true
SENTRY_ENVIRONMENT=development
PIPELINE_MAX_RUNTIME_SECONDS=1600
TASK_ESCALATION_SECONDS=3600

Optional environment

export CLOUD_TASKS_LOCATION="us-central1"
export BUBBLE_INVOICES_QUEUE="nest-bubble-invoices"
export CLOUD_TASKS_SERVICE_ACCOUNT="..."
export PARTNERCREDS_SERVICE_BASE_URL="https://<partnercreds-cloud-run-url>"

Install dependencies

# From repo root
uv sync --all-packages

Run locally

# From repo root
uv run --package handler granian --interface asgi services.handler.main:app --host 0.0.0.0 --port 8080 --workers 1 --loop uvloop

Sanity checks

curl http://localhost:8080/api/v1/health

Notes

  • DEBUG=true enables OpenAPI (/docs) and disables pipeline status updates.
  • You can post a TaskInfo payload directly to any pipeline route to test extraction and loading without Cloud Tasks.

Tests

# From repo root
uv run --package handler pytest -q

Last updated on

Data model

Storage, schemas, and data ownership for Handler

Operations

Deployments, SLOs, and monitoring for Handler