🚧 Projeto “Distributed-KV” – vamos passo a passo 🚧

A atividade pede que o repositório contenha código, Docker, start.sh, documentação, testes e relatório de carga . Para facilitar, proponho dividirmos o trabalho em pastas-marco (milestones). Cada etapa gera uma sub-árvore do repo já funcional, para que possa testar antes de avançar.

---

0 ▸ Road-map até 23 de maio

Semana	Entregável	Conteúdo-chave
hoje	Milestone 1 – Skeleton	Estrutura de diretórios, docker-compose.yml mínimo, start.sh, README rascunho
+2 d	Milestone 2 – API & Consumer	FastAPI (Python 3.12) + health-checks, RabbitMQ publish/consume, SQLite fallback
+4 d	Milestone 3 – Cache & LB	Redis cluster + Nginx LB (round-robin, timeouts)
+5 d	Milestone 4 – Escalabilidade	Variáveis de escala (--scale api=3 consumer=3), readiness probes, autoscale notes
+6 d	Milestone 5 – Testes de carga	Scripts k6/Locust, target ≤ 1 s por request, retries=5
+7 d	Milestone 6 – Docs finais	Swagger/OpenAPI, relatório, diagrama arquitetura, guia cloud-deploy

(Se precisar encurtar, juntamos 3 + 4 ou 5 + 6.)

---

1 ▸ Milestone 1 – Skeleton do repositório

text
distributed-kv/
├── api/                 # FastAPI service
│   ├── main.py
│   ├── models.py
│   └── requirements.txt
├── consumer/            # Worker que processa filas
│   └── worker.py
├── infra/               # Docker, Nginx, Redis, RabbitMQ, CockroachDB
│   ├── docker-compose.yml
│   └── nginx/
│       └── nginx.conf
├── scripts/
│   └── start.sh
├── tests/
│   └── load/            # k6 ou Locust
└── docs/
    ├── architecture.md
    ├── api.md           # Swagger gera aqui
    └── README.md

a) start.sh (bootstrap único exigido)

bash
#!/usr/bin/env bash
set -e
echo "⏳ Build & up containers..."
docker compose -f infra/docker-compose.yml pull
docker compose -f infra/docker-compose.yml up -d --build
echo "✅ Cluster running – veja http://localhost/docs para Swagger."

b) infra/docker-compose.yml – esqueleto mínimo

O slide “Exemplo – API para key-value (Ficheiro compose)” (p. 13, Aula 12) já mostra um template . A versão inicial reduzida:

yaml
version: "3.8"
services:
  api:
    build: ../api
    ports: ["8000:8000"]
    depends_on: [redis, rabbitmq, db]
    environment:
      REDIS_HOST: redis
      AMQP_HOST: rabbitmq
      DB_HOST: db

  consumer:
    build: ../consumer
    depends_on: [rabbitmq, db]
    environment:
      AMQP_HOST: rabbitmq
      DB_HOST: db

  redis:
    image: redis:7.2-alpine
    ports: ["6379:6379"]

  rabbitmq:
    image: rabbitmq:3-management
    ports: ["15672:15672", "5672:5672"]

  db:
    image: cockroachdb/cockroach:v24.1.0
    command: start-single-node --insecure
    ports: ["26257:26257"]

networks: { default: {} }

*(Redis e RabbitMQ em cluster virão nos próximos marcos – ver slides Aula 10 & 11) *

---

2 ▸ Como vamos trabalhar “pasta por pasta”

1. Você confirma: “Ok, cria a pasta X”.
2. Eu envio o conteúdo completo dessa pasta (código ou configs) + explicação de como testar.
3. Você roda localmente (./scripts/start.sh, docker compose logs etc.) e dá feedback.
4. Seguimos para a próxima.

Isso garante que nunca entrego um dump gigante e você controla o ritmo.

---

Próximo passo

Quer começar gerando a pasta api/ com o FastAPI básico e endpoint /kv (GET/PUT/DELETE)?
Ou prefere primeiro fechar o docker-compose.yml e start.sh?

Diga qual pasta atacamos primeiro e já lhe envio o conteúdo completo. 😉

Pasta consumer/ – Worker que processa as filas RabbitMQ 🛠️

Siga estes três ficheiros (coloque-os dentro de distributed-kv/consumer/):

---

1. Dockerfile

dockerfile
FROM python:3.12-slim

WORKDIR /app

# dependências
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# código
COPY worker.py .

CMD ["python", "worker.py"]

---

2. requirements.txt

text
pika==1.3.2          # RabbitMQ (AMQP)
psycopg[binary]==3.1.18   # CockroachDB/Postgres
redis==5.0.4         # cache
python-dotenv==1.0.1 # ler variáveis locais, se quiser

---

3. worker.py

python
import json, os, time, logging
import pika, psycopg, redis
from psycopg.rows import dict_row

logging.basicConfig(level=logging.INFO,
                    format="%(asctime)s %(levelname)s %(message)s")

# ── 1. Parâmetros de ambiente ──────────────────────────────────────────────────
AMQP_HOST  = os.getenv("AMQP_HOST" , "rabbitmq")
DB_HOST    = os.getenv("DB_HOST"   , "db")
DB_PORT    = int(os.getenv("DB_PORT" , 26257))
DB_USER    = os.getenv("DB_USER"   , "root")
DB_PASS    = os.getenv("DB_PASS"   , "")
DB_NAME    = os.getenv("DB_NAME"   , "kv")
REDIS_HOST = os.getenv("REDIS_HOST", "redis")
REDIS_PORT = int(os.getenv("REDIS_PORT", 6379))

# ── 2. Conexões ────────────────────────────────────────────────────────────────
def conn_rmq():
    while True:
        try:
            params = pika.ConnectionParameters(host=AMQP_HOST)
            return pika.BlockingConnection(params)
        except Exception as e:
            logging.warning("RabbitMQ indisponível, retry em 3 s: %s", e)
            time.sleep(3)

def conn_db():
    dsn = f"postgresql://{DB_USER}:{DB_PASS}@{DB_HOST}:{DB_PORT}/{DB_NAME}"
    while True:
        try:
            return psycopg.connect(dsn, autocommit=True, row_factory=dict_row)
        except Exception as e:
            logging.warning("DB indisponível, retry em 3 s: %s", e)
            time.sleep(3)

def ensure_schema(cur):
    cur.execute("""
        CREATE TABLE IF NOT EXISTS kv_store (
            key TEXT PRIMARY KEY,
            value TEXT,
            last_updated TIMESTAMPTZ DEFAULT now()
        )
    """)

rmq = conn_rmq()
channel = rmq.channel()
channel.queue_declare("add_key")
channel.queue_declare("del_key")

db   = conn_db()
cur  = db.cursor()
ensure_schema(cur)

rcache = redis.Redis(host=REDIS_HOST, port=REDIS_PORT, decode_responses=True)

# ── 3. Handlers ────────────────────────────────────────────────────────────────
MAX_RETRIES = 5

def handle_add(ch, method, properties, body):
    try:
        payload = json.loads(body)
        k, v, ts = payload["key_name"], payload["key_value"], payload["timestamp"]
        cur.execute("""
            INSERT INTO kv_store (key, value, last_updated)
            VALUES (%s,%s,%s)
            ON CONFLICT (key)
            DO UPDATE SET value = EXCLUDED.value, last_updated = EXCLUDED.last_updated
            WHERE kv_store.last_updated <= EXCLUDED.last_updated
        """, (k, v, ts))
        # cache “write through”
        rcache.set(k, v)
        logging.info("[add_key] %s=%s", k, v)
        ch.basic_ack(method.delivery_tag)
    except Exception as e:
        logging.error("[add_key] erro: %s", e)
        ch.basic_nack(method.delivery_tag, requeue=False)

def handle_del(ch, method, properties, body):
    try:
        payload = json.loads(body)
        k, ts = payload["key_name"], payload["timestamp"]
        # verifica se há versão mais recente
        cur.execute("SELECT last_updated FROM kv_store WHERE key=%s", (k,))
        row = cur.fetchone()
        if row and row["last_updated"] <= ts:
            cur.execute("DELETE FROM kv_store WHERE key=%s", (k,))
            rcache.delete(k)
            logging.info("[del_key] %s removida", k)
        ch.basic_ack(method.delivery_tag)
    except Exception as e:
        logging.error("[del_key] erro: %s", e)
        ch.basic_nack(method.delivery_tag, requeue=False)

channel.basic_consume("add_key", handle_add)
channel.basic_consume("del_key", handle_del)

logging.info("🟢 Consumer a escutar filas…")
channel.start_consuming()

O fluxo baseia-se no snippet de consumidor apresentado nos slides da Aula 12, pág. 15, adaptado para Python e CockroachDB/Redis.

---

Como testar

1. Suba o cluster (na raiz do projeto):

   bash
   ./scripts/start.sh          # já existente
   docker compose logs -f consumer

2. Publique uma chave:

   bash
   curl -X PUT -H "Content-Type: application/json" \
        -d '{"data":{"key":"foo","value":"bar"}}' http://localhost:8000/kv

3. Verifique no log do consumer que a mensagem add_key foi processada e o valor guardado em DB + Redis.

4. Apague:

   bash
   curl -X DELETE "http://localhost:8000/kv?key=foo"

   O consumer processará del_key e retirará a entrada.

---

Próximo passo

Quando confirmar que o consumer está a funcionar, podemos avançar para a pasta tests/ (scripts de carga k6/Locust) ou para cluster Redis + Nginx – você escolhe. 😉

Por quê o docker compose falhou

O erro

failed to read dockerfile: open Dockerfile: no such file or directory

significa que, dentro do context indicado no docker-compose.yml, o Docker não encontra um ficheiro chamado Dockerfile.
No seu caso está a acontecer para consumer/ (e possivelmente para api/, que parece ter um Dockerfile vazio - “2 B done”).

No exemplo-guia da Aula 12 o docker-compose.yml aponta para ./api, assumindo que o ficheiro está na mesma pasta do compose .

Como na nossa estrutura o compose vive em infra/, usamos ../consumer e ../api:

text
infra/docker-compose.yml
   build: ../consumer      # caminho relativo à pasta infra

Se o ficheiro não existir (ou está vazio) o build falha.

---

Check-list rápida para corrigir

1. Confirme os caminhos

   bash
   tree -L 2
   # deve mostrar:
   # distributed-kv/
   # ├── api/
   # │   └── Dockerfile
   # ├── consumer/
   # │   └── Dockerfile
   # └── infra/
   #     └── docker-compose.yml

2. Crie/preencha o Dockerfile em cada serviço

   api/Dockerfile (min version – FastAPI + Uvicorn):

   dockerfile
   FROM python:3.12-slim
   
   WORKDIR /app
   COPY requirements.txt .
   RUN pip install --no-cache-dir -r requirements.txt
   
   COPY . .
   CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

   consumer/Dockerfile (o que lhe enviei):

   dockerfile
   FROM python:3.12-slim
   WORKDIR /app
   COPY requirements.txt .
   RUN pip install --no-cache-dir -r requirements.txt
   COPY worker.py .
   CMD ["python", "worker.py"]

3. Garanta que o nome do ficheiro é exactamente Dockerfile
   (sem extensão, sem maiúsculas diferentes).

4. Volte a executar

   bash
   ./scripts/start.sh          # isto corre ‘docker compose up -d --build’
   docker compose -f infra/docker-compose.yml ps

   Agora deverá ver api, consumer, db, rabbitmq, redis todos em Up.

---

Dicas se preferir evitar caminhos relativos

• Mover o docker-compose.yml para a raiz do projecto e mudar build: ./api etc.
  Assim corre apenas docker compose up a partir da raiz.

• Ou, dentro de infra/docker-compose.yml, use:

  yaml
  api:
    build:
      context: ../api
      dockerfile: Dockerfile   # opcional mas explícito

---

Próximo passo

Assim que confirmar que o cluster sobe sem erros:

1. Teste a API:

   bash
   curl -X PUT -H "Content-Type: application/json" \
        -d '{"data":{"key":"foo","value":"bar"}}' http://localhost:8000/kv
   curl http://localhost:8000/kv?key=foo

2. Veja os logs do consumer para validar que processa as filas:

   bash
   docker compose -f infra/docker-compose.yml logs -f consumer

Se tudo ok, diga-me e avançamos para a próxima pasta (Redis cluster + Nginx LB ou os scripts de testes de carga – como preferir).

🚑 O api não arrancou porque o binário uvicorn não existe dentro da imagem
O erro do Docker diz exatamente isso:

exec: "uvicorn": executable file not found in $PATH

Isso acontece quando:

1. uvicorn não foi instalado (faltou na requirements.txt ou no pip install);
2. O CMD/ENTRYPOINT do Dockerfile chama “uvicorn” diretamente, mas o pacote não está lá.

---

1 ▸ Crie/actualize a pasta api/

text
distributed-kv/
└── api/
    ├── main.py
    ├── requirements.txt
    └── Dockerfile

api/requirements.txt

text
fastapi==0.111.0
uvicorn[standard]==0.29.0     # servidor ASGI
pika==1.3.2                   # para publicar nas filas
redis==5.0.4                  # ler cache
psycopg[binary]==3.1.18       # Cockroach/Postgres
python-dotenv==1.0.1

Se quiser versões diferentes, sinta-se livre – mas inclua sempre uvicorn.

---

api/main.py – versão mínima já funcional

python
import os, json, datetime
import asyncio
import redis, pika, psycopg
from fastapi import FastAPI, HTTPException, status, Query, Body
from pydantic import BaseModel

app = FastAPI(title="Distributed-KV API")

# ─── Config ───────────────────────────────────────────────────────────────
REDIS_HOST = os.getenv("REDIS_HOST", "redis")
AMQP_HOST  = os.getenv("AMQP_HOST" , "rabbitmq")
DB_HOST    = os.getenv("DB_HOST"   , "db")
DB_PORT    = int(os.getenv("DB_PORT", 26257))

redis_cli = redis.Redis(host=REDIS_HOST, decode_responses=True)

pg = psycopg.connect(
    f"postgresql://root@{DB_HOST}:{DB_PORT}/kv",
    autocommit=True
)
with pg.cursor() as cur:
    cur.execute("""CREATE TABLE IF NOT EXISTS kv_store(
        key TEXT PRIMARY KEY,
        value TEXT,
        last_updated TIMESTAMPTZ DEFAULT now()
    )""")

# RabbitMQ – canal único a reusar
mq_conn = pika.BlockingConnection(pika.ConnectionParameters(host=AMQP_HOST))
mq_chan = mq_conn.channel()
mq_chan.queue_declare("add_key")
mq_chan.queue_declare("del_key")

# ─── Modelos ──────────────────────────────────────────────────────────────
class KVPayload(BaseModel):
    key:   str
    value: str

# ─── End-points ────────────────────────────────────────────────────────────
@app.get("/kv", summary="Obter value por key")
def get_kv(key: str = Query(...)):
    # primeiro tenta Redis
    val = redis_cli.get(key)
    if val is not None:
        return {"data": {"value": val, "source": "redis"}}
    # senão BD
    with pg.cursor() as cur:
        cur.execute("SELECT value FROM kv_store WHERE key = %s", (key,))
        row = cur.fetchone()
        if row:
            redis_cli.set(key, row[0])
            return {"data": {"value": row[0], "source": "db"}}
    raise HTTPException(status_code=404, detail="Key not found")

@app.put("/kv", status_code=status.HTTP_202_ACCEPTED, summary="Colocar/atualizar key")
def put_kv(payload: KVPayload = Body(...)):
    msg = {
        "key_name":  payload.key,
        "key_value": payload.value,
        "timestamp": datetime.datetime.utcnow().isoformat()
    }
    mq_chan.basic_publish("", "add_key", json.dumps(msg).encode())
    return {"queued": "add_key"}

@app.delete("/kv", status_code=status.HTTP_202_ACCEPTED, summary="Apagar key")
def del_kv(key: str = Query(...)):
    msg = {"key_name": key, "timestamp": datetime.datetime.utcnow().isoformat()}
    mq_chan.basic_publish("", "del_key", json.dumps(msg).encode())
    return {"queued": "del_key"}

---

api/Dockerfile

dockerfile
FROM python:3.12-slim

# ➊ instalar dependências Python
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# ➋ copiar código
COPY . .

# ➌ arrancar servidor ASGI
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

(Se preferir pôr outras flags – --workers, --reload em dev – fique à vontade.)

---

2 ▸ Reconstrua e suba

bash
./scripts/start.sh      # ele já faz o --build
docker compose -f infra/docker-compose.yml logs -f api

Você deve ver algo como:

text
INFO:     Started server process [1]
INFO:     Uvicorn running on http://0.0.0.0:8000

---

3 ▸ Teste rápido

bash
curl -X PUT -H "Content-Type: application/json" \
     -d '{"key":"foo","value":"bar"}' http://localhost:8000/kv

curl http://localhost:8000/kv?key=foo
curl -X DELETE http://localhost:8000/kv?key=foo

Nos logs do consumer deverá aparecer o processamento das filas (add_key / del_key).

---

Próxima pasta?

• Agora que api e consumer estão vivos, escolha o próximo passo:
  • Redis cluster + Nginx load-balancer (para escalar a cache e pôr LB em frente às APIs)
  • tests/ (scripts k6/Locust + relatório)

É só dizer qual atacamos primeiro! 🚀

⚠️ A API falhou porque a base de dados “kv” ainda não existe no CockroachDB
O Cockroach arrancou vazio (start-single-node --insecure) e cria apenas a BD defaultdb.
Quando o main.py abre a ligação para …/kv, o driver devolve psycopg.errors.InvalidName: no database or schema specified.

---

➊ Correção rápida (já em containers a correr)

bash
# entre no nó Cockroach e crie a BD
docker exec -it infra-db-1 cockroach sql --insecure -e "CREATE DATABASE kv;"

Assim que a base existir, faça docker compose restart api consumer e tudo deve subir sem erros.

---

➋ Alternativa “sempre funciona”: inicializar a BD no start-up

Edite infra/docker-compose.yml para acrescentar um init command:

yaml
  db:
    image: cockroachdb/cockroach:v24.1.0
    command: >
      bash -c "
        cockroach start-single-node --insecure --listen-addr=0.0.0.0 &&
        sleep 3 &&
        cockroach sql --insecure -e 'CREATE DATABASE IF NOT EXISTS kv;'"

(mantém tudo no mesmo serviço, sem sidecar extra)

---

➌ Ou ainda: ligar primeiro a defaultdb e criar a “kv” via código

Atualize api/main.py (mesma lógica vale para consumer/worker.py):

python
DB_NAME = os.getenv("DB_NAME", "kv")          # default “kv”
dsn_root = f"postgresql://root@{DB_HOST}:{DB_PORT}/defaultdb"

with psycopg.connect(dsn_root, autocommit=True) as conn:
    with conn.cursor() as cur:
        cur.execute(f"CREATE DATABASE IF NOT EXISTS {DB_NAME}")

dsn_app = f"postgresql://root@{DB_HOST}:{DB_PORT}/{DB_NAME}"
pg = psycopg.connect(dsn_app, autocommit=True)

Dessa forma o serviço cria a BD na primeira execução e as próximas ligações usam-na normalmente.

Se preferir parametrizar tudo, declare DB_NAME=kv nas variáveis de ambiente do api e consumer.

---

Teste rápido após a correção

bash
curl -X PUT -H "Content-Type: application/json" \
     -d '{"key":"foo","value":"bar"}' http://localhost:8000/kv
curl http://localhost:8000/kv?key=foo      # deve devolver {"data":{"value":"bar","source":"redis"}}

No docker compose logs -f api consumer não deverá mais aparecer o InvalidName.

---

Quando confirmar que a API responde, diga se avançamos para:

• Redis cluster + Nginx LB
• Scripts de carga em /tests (k6 ou Locust)

Estou a postos para o próximo passo! 🚀