samo

README

Samo — L7 Load Balancer

Go'da yozilgan L7 HTTP load balancer. Status: M5 — Observability + hot reload.

Hozirgi holat

• M1 — Foundation: binary ishga tushadi, /healthz endpoint
• M2 — Reverse proxy core: round robin balancer, backend pool
• M3 — Balancer algorithms: leastconn, weighted, iphash + benchmark skeleton
• M4 — Health (active+passive), TLS termination, graceful shutdown
• M5 — Prometheus metrics, config hot reload, TLS cert reload, baseline benchmark

Batafsil: docs/MVP-ROADMAP.md.

Talablar

• Go 1.23+
• Make
• golangci-lint v2.1.5 (lint uchun)

Build

make build
./bin/samo -config configs/example.yaml

Konfiguratsiya

Minimal: configs/example.yaml.

Env overlay: har YAML path'ni SAMO_ prefiksi va __ separator bilan override qilish mumkin. Masalan: SAMO_SERVER__LISTEN=:9090 ./bin/samo -config configs/example.yaml

Reverse proxy & balancers

Qo'llab-quvvatlanadigan algoritmlar:

• roundrobin — atomic counter, teng taqsimlash (M2)
• leastconn — eng kam aktiv connection (M3)
• weighted — per-backend weight bo'yicha SWRR (M3)
• iphash — r.RemoteAddr sticky mapping (M3)

Konfiguratsiya namunasi: configs/example.yaml. /healthz lokal samo tomonidan javob beriladi. Barcha backend'lar ishlamasa — 503 + Retry-After: 5.

Health checks

Samo ikki turdagi health check'ni qo'llab-quvvatlaydi:

• Active — har backend'ga interval'da HTTP GET. Konsekutiv unhealthy_threshold fail backend'ni alive=false qiladi. healthy_threshold pass bo'lsa backend qayta tiklanadi.
• Passive — oxirgi window_size so'rov natijalari ring buffer'da saqlanadi. min_samples to'lgach va error rate threshold'dan oshsa, backend ejection_duration davomida quarantine qilinadi.

Konfiguratsiya: configs/example.yaml ichidagi health: bloki.

TLS

server.tls.enabled: true bo'lsa Samo cert_file va key_file bilan HTTPS eshitadi. Min versiya 1.2 yoki 1.3. SIGHUP paytida cert/key fayllari qayta o'qiladi va yangi TLS handshake'lar yangi sertifikatni oladi.

Metrics

telemetry.metrics.enabled: true (default) bilan Samo /metrics endpoint'ida Prometheus formatda metrika chiqaradi:

• samo_requests_total{backend,method,status}
• samo_request_duration_seconds{backend,method}
• samo_backend_up{backend} va samo_active_connections{backend}
• samo_healthcheck_total{backend,result} va samo_healthcheck_duration_seconds{backend}
• samo_config_reload_total{status}, samo_passive_ejections_total{backend}
• samo_build_info{version}

Path konfiguratsiya: telemetry.metrics.path (default /metrics).

Config hot reload

kill -HUP <pid> Samo config faylini qayta o'qiydi. Reloadable: backends, balancer, health.*, telemetry.log.level, server.tls.cert_file/key_file. Boshqa o'zgarishlar (server.listen, timeout'lar, server.tls.enabled, metrics path) restart talab qiladi va warning bilan ignor qilinadi.

Config validate fail bo'lsa eski config saqlanadi va samo_config_reload_total{status="fail"} oshadi. Tafsilot: docs/adr/0005-config-hot-reload.md.

Graceful shutdown

SIGTERM yoki SIGINT kelganda Samo yangi connection qabul qilmaydi, aktiv so'rovlarni server.shutdown_timeout ichida tugatadi, health checker goroutine'larini yopadi va clean exit qiladi.

Demo

Docker Compose bilan 3 backend'li demo:

make demo-up        # samo + 3 echo backend
curl http://127.0.0.1:8080/
make demo-down

Batafsil: docs/demo.md.

Test

make test           # unit
make race           # race detector bilan
make test-integration
make ci             # lokal'da CI pipeline to'liq

Load test

Minimal baseline (vegeta):

make demo-up
make load-test

Batafsil: test/load/README.md.

Benchmark

Baseline natijalari: docs/benchmarks/m5.md. Lokal qayta ishga tushirish: make demo-up && make load-test.

Loyiha hujjatlari

• docs/DESIGN.md — arxitektura
• docs/MVP-ROADMAP.md — milestone'lar
• docs/adr/ — qarorlar (ADR)
• docs/plans/ — implementation plan'lari

Litsenziya

MIT — LICENSE.