Files

Apple c552199eed chore: organize documentation structure for monorepo

- Create /docs structure (microdao, daarion, agents)
- Organize 61 cursor technical docs
- Add README files for each category
- Copy key documents to public categories
- Add GitHub setup instructions and scripts

2025-11-15 04:08:35 -08:00

12 KiB

Raw Blame History

35 — MicroDAO Service Mesh Design (MicroDAO)

Арова архітектура сервіс-меш, резолюція сервісів, мережеві політики, zero-trust, observability, retries, autoscaling та інженерні стандарти для DAARION.city / microDAO

1. Purpose & Scope

MicroDAO Service Mesh — це внутрішня мережна платформа, що забезпечує:

безпечний виклик сервісів через zero-trust модель;
внутрішнє балансування навантаження;
автоматичне перез'єднання;
контроль трафіку;
observability (metrics / traces / logs);
резолюцію сервісів та політики доступу;
fault tolerance (retries, circuit breakers, rate limits).

Цей документ — обов'язковий для:

backend-інженерів,
DevOps/SRE,
авторів внутрішніх сервісів,
security-аудиторів.

2. High-Level Mesh Architecture

                           ┌────────────────────────────────┐
                           │         API Gateway (PEP)      │
                           └────────────────┬───────────────┘
                                            │
                         ┌──────────────────┴─────────────────┐
                         │        SERVICE MESH FABRIC         │
                         └─────────────┬─────────────┬────────┘
                                       │             │
                     ┌─────────────────┘             └──────────────────┐
               Internal Services                                   System Services

Основу складають:

Service Registry
Sidecar Proxy (Envoy / Linkerd / Traefik Mesh)
mTLS між сервісами
Observability pipeline
Traffic control (retries, timeouts, circuit breakers)

3. Zero-Trust Model

Платформа працює за правилом:

НІЯКІ ВНУТРІШНІ СЕРВІСИ НЕ ДОВІРЯЮТЬ ОДИН ОДНОМУ.

Тому кожен запит:

автентифікується,
авторизується через PDP,
шифрується,
логуються метадані.

3.1 Trust Boundaries

Boundary	Policy
Gateway → Services	PDP enforced
Service → Service	mTLS + service identity
Service → DB	minimal DB roles
Service → NATS	per-stream permissions

4. Service Identity (mTLS)

Кожен сервіс отримує власну сертифікацію:

CN = service_name
SAN = service_name.namespace.svc

mTLS забезпечує:

автентифікацію сервісу,
заборону spoofing,
шифрування трафіку.

5. Service Registry

Mesh потребує централізованого каталогу сервісів:

{
  "service": "wallet",
  "host": "wallet.svc.cluster.local",
  "port": 8081,
  "metadata": {
      "team": "core",
      "version": "v1.4.0",
      "zone": "eu-central-1"
  }
}

У cloud-середовищі це зазвичай:

Kubernetes DNS,
або Consul,
або власний registry.

6. Internal Service-to-Service Traffic

6.1 Pattern

serviceA → Envoy Sidecar → Mesh → Envoy Sidecar → serviceB

6.2 Benefits

automatic retries,
circuit breaking,
mTLS,
observability,
fine-grained routing,
traffic shadowing.

7. Core Service Mesh Features

7.1 mTLS Encryption

Усі внутрішні запити шифровані.
Certificates rotate every 12–48 hours.

7.2 Load Balancing (Layer 7)

round-robin,
least_conn,
locality-aware routing.

7.3 Retries

max 3,
exponential backoff,
jitter.

7.4 Circuit Breakers

При перевантаженні:

mesh відкриває circuit → запити йдуть у failfast,
після cooling-off — пробує відновити.

7.5 Timeouts

default timeout: 3 seconds,
wallet, embassy: 1 second (short to avoid blocking),
agent runs: 10–60 seconds (handled separately).

8. Internal API Standard (Mesh Requirements)

Кожен сервіс має відповідати стандарту:

JSON over HTTP (no gRPC unless planned),
/internal/v1/<service>/<operation>,
атомарні операції,
4xx для клієнтських помилок,
5xx для сервісних.

Приклад:

POST /internal/v1/wallet/payout/claim
POST /internal/v1/embassy/energy/update
POST /internal/v1/agent/run

9. PDP Integration (per-service)

PEP живе тільки у API Gateway, але Services повинні:

не довіряти payload, навіть після PDP → додаткова валідація;
виконувати DB-level ACL checks;
мутуючі операції мають виконуватись тільки через Gateway.

Жоден сервіс не приймає зовнішній трафік напряму.

10. Mesh-Level Policies

10.1 Allow-lists

Кожен сервіс може викликати тільки перелік інших сервісів:

Service	Allowed to Call
Messaging	Usage, Storage
Agent Orchestrator	LLM Proxy, Usage
Embassy	RWA, Usage
Wallet	Chain RPC, Usage
Router	Agent Orchestrator, LLM Proxy
RWA	Wallet, Usage

10.2 Deny-lists

Забезпечує Zero-Trust:

Messaging → No direct Wallet access
Agents → No direct RWA access
Embassy → No direct Wallet claim
Router → No low-level DB access

11. Observability Model

Mesh забезпечує повну видимість.

11.1 Metrics

latency (p50, p95, p99),
HTTP codes,
retry count,
circuit breaker events,
request sizes,
traffic spikes.

11.2 Tracing

Підтримується:

OpenTelemetry,
distributed tracing (trace_id, span_id),
propagation через Gateway → Mesh → Services → DB → NATS.

11.3 Logs

Збираються:

access logs,
error logs,
mesh-level logs.

12. Failover & Resilience

12.1 Multi-zone (Cloud)

Mesh обирає найближчий healthy інстанс.

12.2 Zonal Failover

При провалі зони:

трафік автоматично перенаправляється в інші зони.

12.3 Service Healthchecks

livenessProbe: чи не висить процес.
readinessProbe: чи сервіс готовий приймати трафік.

13. Mesh Traffic Rules for Critical Services

13.1 Wallet Service

low timeout (1 sec)
retries: 0 (щоб не дублювати транзакції)
circuit-breaker sensitivity: high

13.2 Embassy

retries: 1
timeout: 0.5 sec
global rate limiting:
- embassy bursts можуть спричинити навантаження

13.3 Agent Orchestrator

long timeout (10–60 sec)
retries: none (idempotency?)
dedicated queue routing

13.4 Router/DAARWIZZ

timeout: 5–15 sec
retries: 1–2
concurrency caps

14. Service Mesh Security

14.1 mTLS Everywhere

між усіма сервісами обов'язково.

14.2 Internal Service Keys

Кожен сервіс має:

service_key,

capability:

service.write.oracles
service.mint.payout
service.agent.run
service.read.usage

PDP авторизація на рівні сервісів.

14.3 No direct DB access (where possible)

Сервіси мають мінімальні ролі DB.

14.4 Network Policies

Забороняють:

доступ між сервісами, що не пов'язані функціонально,
будь-які вихідні запити (egress) без дозволу.

15. Deployment Model

15.1 Sidecar Mode

Рекомендовано:

Envoy sidecar у кожному pod,
mesh контролер керує routing tables.

15.2 Node-agent Mode (Alternative)

не потрібні sidecars,
менше накладних витрат,
простіше управління.

15.3 Observability stack

Prometheus,
Grafana,
Loki (або Cloud Logging),
Jaeger / Tempo.

16. Service Mesh Integration with Scaling

16.1 Auto-discovery

Нові інстанси автоматично реєструються.

16.2 Load-aware routing

Mesh відправляє запити на:

найменш завантажені інстанси,
локальні (в межах зони).

16.3 Autoscaling Signals

Mesh збирає:

CPU,
memory,
request rate,
errors,
queue depth (for agents).

17. Message Patterns

17.1 Request-Response

Звичайні виклики:

Messaging
Projects
Wallet reads

17.2 Asynchronous Events

Через NATS:

payouts,
RWA updates,
agent events

17.3 Long-running tasks

Через Agent Orchestrator:

LLM chain-of-thought,
multi-step flows.

18. Example Mesh Policy Config (Illustrative)

# service: wallet
allow:
  - usage
  - chain_rpc
deny:
  - messaging
  - router
  - embassy

timeouts:
  request: 1s

retries:
  enabled: false

mTLS: required

# service: embassy
allow:
  - rwa
  - usage
deny:
  - wallet
  - agent
  - router

mTLS: required
rate_limit: 500/min

19. Integration with Other Docs

Цей документ доповнює:

34_internal_services_architecture.md
33_api_gateway_security_and_pep.md
32_policy_service_PDP_design.md
29_scaling_and_high_availability.md
26_security_audit.md

20. Завдання для Cursor

You are a senior DevOps/SRE engineer. Implement Service Mesh using:
- 35_microdao_service_mesh_design.md
- 34_internal_services_architecture.md
- 29_scaling_and_high_availability.md

Tasks:
1) Set up Service Registry (Kubernetes DNS or Consul).
2) Configure mTLS for all services.
3) Implement Envoy sidecar proxies (or node-agent mode).
4) Set up mesh-level policies (allow-lists, deny-lists).
5) Configure retries, timeouts, circuit breakers.
6) Integrate with observability stack (Prometheus, Grafana, Loki, Jaeger).
7) Set up health checks for all services.
8) Configure load balancing and failover.
9) Implement network policies for zero-trust.

Output:
- list of modified files
- diff
- summary

21. Summary

MicroDAO Service Mesh забезпечує:

захищені зв'язки між сервісами,
шифрування всього внутрішнього трафіку,
централізоване управління політиками,
fault tolerance,
трасування,
динамічну маршрутизацію,
стійкість до збоїв.

Це «нервова система» DAARION.city, яка дозволяє системі масштабуватися й залишатися безпечною при зростанні навантаження та сервісів.

Версія: 1.0
Останнє оновлення: 2024-11-14

12 KiB Raw Blame History Unescape Escape