# Spec — Golden Path `rest-api/python`

**Versión del shape:** 1.0.0
**Status:** Activo (free-trial entry point)
**ADR de referencia:** ADR-027 (Golden Paths Fase 5), ADR-053 (anatomía
del shape web-backend/python — referencia para decisiones de empaque),
**ADR-060 Fase 1 (`GATEWAY-API-MIGRATION`): ingress = Traefik Proxy + Gateway
API (`HTTPRoute`), reemplaza el `rke2-ingress-nginx` de ADR-053 §11.1**,
ADR-061 (workflow CI self-contained — sin `uses:` cross-repo; `helm-deploy`
inline sin `container:`)
**Visibilidad:** interna de Coralware — este spec NO se sincroniza al
repo Gitea ni al repo del cliente.

---

## 1. Propósito

Definir el comportamiento del shape `rest-api/python` — scaffold de API
HTTP stateless en FastAPI, sin persistencia. Es el shape **entry point**
para tier `free-trial`: el cliente arranca rápido con un endpoint REST
funcional sin tener que decidir BD, migraciones ni hooks.

Cuando un cliente necesita persistencia, debería **migrar a
`web-backend/python`** (ADR-053), no extender este shape para incluir DB.

---

## 2. Contrato del shape

### 2.1 Entradas

| Entrada | Origen | Descripción |
|---------|--------|-------------|
| `__APP_NAME__` | placeholder | Sustituido server-side por `repo-provisioner` |
| `__TENANT_ID__` | placeholder | UUID del tenant |
| `__TENANT_ID_NODASHES__` | placeholder | UUID sin guiones, para DNS y namespaces |
| `__TIER__` | placeholder | `free-trial` | `startup` | `business` | `enterprise` |
| `KUBECONFIG_TENANT_B64` | secret de proyecto Gitea | Provisto por `tenant-manager` |
| `vars.TENANT_ID`, `vars.TENANT_ID_NODASHES`, `vars.TENANT_TIER` | vars de proyecto | Provisto por `tenant-manager` |

### 2.2 Salidas observables

| Salida | Forma |
|--------|-------|
| Imagen Docker | `registry.coralsafety.com/t-<tenant-id-short>/<APP_NAME>:<tag>` — proyecto Harbor dedicado del tenant (ADR-019 D-03) |
| Helm release | `<APP_NAME>` en namespace `apps` del cluster tenant (ADR-054) |
| App reachable | `https://<APP_NAME>.<tenant-id-con-guiones>.apps.coralware.cloud/health` retorna 200 (FQDN subdominio DOT, ADR-067/ADR-082 — reconciliado drift previo que usaba el host plano con guion) |
| Ingress controller | **Traefik Proxy + Gateway API** en `traefik-system` (bundle Fleet `traefik-bootstrap`) — ADR-060 Fase 1 (`GATEWAY-API-MIGRATION`); reemplaza `rke2-ingress-nginx` (EOL marzo 2026). El shape emite un `HTTPRoute` adjunto al `Gateway` `tenant-gateway` (ns `apps`, stack-deployer §3c). Paridad con web-backend/python |
| TLS | Wildcard per-tenant `*.<tenant-id>.apps.coralware.cloud` vía Secret `tenant-wildcard-tls` (cert-manager local del cluster, ADR-067 — reconciliado drift previo que citaba el `apps-wildcard-tls` compartido de Fase 0) |
| Endpoints obligatorios | `/health`, `/docs`, `/openapi.json`, `/metrics` |

### 2.3 Invariantes

- App stateless — ningún componente persistente requerido.
- `/health` retorna 200 con `{"status":"ok"}` siempre que el proceso esté vivo.
- `helm upgrade --install` del chart funciona **sin `--no-hooks`**. El
  `ServiceAccount` se materializa como hook `pre-install,pre-upgrade`
  (`hook-weight: -5`, `hook-delete-policy: before-hook-creation`) por paridad
  con el shape `web-backend/python`. Este shape no tiene Job de migración, así
  que el hook no es estrictamente necesario — se mantiene para coherencia entre
  ambos charts.
- SecurityContext: `runAsNonRoot=true`, `readOnlyRootFilesystem=true`,
  `drop ALL caps`.
- Sin IPs hardcoded; sin credenciales en código.
- Errores de servicios upstream **NO crashean** la app — se reportan en
  el endpoint que los invoca, el proceso sigue.

---

## 3. Flujo principal

```mermaid
flowchart TD
    dev_push([Dev hace git push\nal repo Gitea del tenant]) --> quality_gate[quality_gate\nruff + black + bandit + pytest --cov 80]
    quality_gate -- fail --> pipeline_failed([pipeline_failed\nHelm no se invoca])
    quality_gate -- ok --> image_build[image_build\nbuildx push a Harbor t-short]
    image_build -- fail --> pipeline_failed
    image_build -- ok --> helm_deploy[helm_deploy\nhelm upgrade --install --wait]
    helm_deploy --> rollout_apply[rollout_apply\nDeployment con nuevo image tag]
    rollout_apply --> rollout_status_check[rollout_status_check\nkubectl rollout status timeout 3m]
    rollout_status_check -- fail --> helm_rollback_manual([helm_rollback_manual\ndev decide rollback\npipeline_failed])
    rollout_status_check -- ok --> smoke_health_check[smoke_health_check\nwget /health 200]
    smoke_health_check -- fail --> investigate([investigate\nlogs + events\npipeline_failed])
    smoke_health_check -- ok --> app_running([app_running])
```

**Sin nodo `alembic_hook`** — diferencia clave con `web-backend/python`.
Los node IDs son labels Prometheus futuros.

---

## 4. Estados terminales

| Estado | Significado | Acción del dev |
|--------|-------------|----------------|
| `app_running` | Todo OK — app desplegada, /health 200 | Ninguna |
| `pipeline_failed` | Quality o build falló | Inspeccionar logs CI; corregir; push |
| `helm_rollback_manual` | Rollout no estabilizó en 3 min | `helm rollback`; investigar pod events |
| `investigate` | Smoke falla aunque rollout terminó | Logs Deployment + cluster events |

---

## 5. Comportamiento fail-safe

- **Servicio upstream caído:** endpoint responde 503 con detalle, app sigue.
- **Imagen no disponible:** `ImagePullBackOff` visible en Rancher; rollout no avanza.
- **Variable de entorno faltante (ej. `LOG_LEVEL`):** default seguro, no crash.

---

## 6. Pruebas negativas

| ID | Prueba | Estado terminal esperado |
|----|--------|--------------------------|
| N1 | Test fallando | `pipeline_failed` en `quality_gate` |
| N2 | Imagen tag inexistente | `ImagePullBackOff` visible en Rancher |
| N3 | Probe `/health` removido del pod | Rollout falla → `helm_rollback_manual` |

(Set reducido vs. web-backend/python; sin pruebas de DB porque no hay BD.)

---

## 7. Versionado del shape

`coralware-shape.yaml` declara `shapeVersion` (semver). Mismas reglas
que `web-backend/python` (ver ADR-053 §7).

---

## 8. Sincronización a Gitea

`templates/rest-api-python/` (este repo IDP) → `idp-templates/template-rest-api-python` (Gitea).

Exclusiones del sync:

- `openspec/` — gobernanza interna del golden path.
- `.ruff_cache/`, `__pycache__/`, `.pytest_cache/`.

Mecanismo: `rsync --exclude='openspec/' --exclude-from=.gitignore`
desde el scaffold local hacia el clone temporal del repo Gitea.

---

## 9. Promoción a web-backend/python

Si la app crece y necesita persistencia:

1. Cliente clona el template `web-backend/python` en un repo nuevo.
2. Migra rutas de su app `rest-api` al nuevo scaffold.
3. Coralware provisiona el `AddonClaim` MariaDB (manual via runbook hasta
   ADR-052).

No hay path de migración in-place — son shapes distintos por diseño.