Projetando o Protocolo
Video da aula estara disponivel em breve
Projeto do modulo: Mesh Protocol para harness.os
Neste modulo final, vamos aplicar tudo que aprendemos para projetar e implementar um protocolo de comunicacao para o mesh do harness.os. O objetivo e que nodes do mesh (marco.ai, build.ai, cortex.ai) possam trocar conhecimento, sincronizar estado e coordenar agentes.
Design de formato de mensagem
Todo protocolo precisa de um formato de mensagem bem definido. Vamos projetar o HMP (Harness Mesh Protocol):
Diagrama
Formato da mensagem HMP:
+─────────────── HEADER (fixo, 32 bytes) ──────────────────+
| Version (1B) | Type (1B) | Flags (2B) | Length (4B) |
| Source ID (16B - UUID) |
| Dest ID (8B - short hash) |
+─────────────── PAYLOAD (variavel) ────────────────────────+
| JSON payload (ate 64KB) |
+───────────────────────────────────────────────────────────+
Version: 1 (primeira versao do protocolo)
Type:
0x01 = KNOWLEDGE_SYNC (sincronizar conhecimento)
0x02 = HEALTH_CHECK (verificar se node esta vivo)
0x03 = SESSION_EVENT (notificar evento de sessao)
0x04 = ROUTE_UPDATE (atualizar tabela de roteamento)
0x05 = AUTH_REQUEST (autenticacao entre nodes)
0x06 = AUTH_RESPONSE (resposta de autenticacao)
Flags:
bit 0: REQUIRES_ACK (precisa de confirmacao)
bit 1: ENCRYPTED (payload criptografado)
bit 2: COMPRESSED (payload comprimido)
bit 3: PRIORITY (alta prioridade)
Python
import struct
import json
import uuid
# Definicao do protocolo HMP
HMP_VERSION = 1
HEADER_FORMAT = "!BBHi16s8s" # network byte order
HEADER_SIZE = struct.calcsize(HEADER_FORMAT) # 32 bytes
# Message types
KNOWLEDGE_SYNC = 0x01
HEALTH_CHECK = 0x02
SESSION_EVENT = 0x03
ROUTE_UPDATE = 0x04
# Flags
FLAG_REQUIRES_ACK = 0x01
FLAG_ENCRYPTED = 0x02
FLAG_COMPRESSED = 0x04
FLAG_PRIORITY = 0x08
def encode_message(msg_type, source_id, dest_id, payload, flags=0):
"""Codifica uma mensagem HMP."""
payload_bytes = json.dumps(payload).encode("utf-8")
src_bytes = uuid.UUID(source_id).bytes
dst_bytes = dest_id.encode("utf-8")[:8].ljust(8, b'\x00')
header = struct.pack(
HEADER_FORMAT,
HMP_VERSION,
msg_type,
flags,
len(payload_bytes),
src_bytes,
dst_bytes
)
return header + payload_bytes
def decode_message(data):
"""Decodifica uma mensagem HMP."""
header = data[:HEADER_SIZE]
version, msg_type, flags, length, src, dst = struct.unpack(
HEADER_FORMAT, header
)
payload = json.loads(data[HEADER_SIZE:HEADER_SIZE + length])
return {
"version": version,
"type": msg_type,
"flags": flags,
"source": str(uuid.UUID(bytes=src)),
"dest": dst.rstrip(b'\x00').decode(),
"payload": payload
}
# Exemplo de uso
msg = encode_message(
msg_type=KNOWLEDGE_SYNC,
source_id="550e8400-e29b-41d4-a716-446655440000",
dest_id="build-ai",
payload={"domain": "build", "knowledge": ["new learning..."]},
flags=FLAG_REQUIRES_ACK
)
print(decode_message(msg))Request/response vs. Pub/sub
Referencia
Padrao Quando usar no mesh Implementacao
────────────── ────────────────────────────── ──────────────
Request/response Knowledge queries, tool calls HTTP/JSON-RPC
"Preciso de uma resposta"
Pub/sub Session events, health status SSE ou WebSocket
"Informo a todos que..."
Hibrido Mesh protocol combina ambos HMP customizado
Tipo 0x01-0x04: req/resp
Tipo 0x03: pub/sub (broadcast)Service discovery
Python
# Service registry para mesh nodes
class MeshRegistry:
def __init__(self):
self.nodes = {}
def register(self, node_id, endpoint, capabilities):
"""Registra um node no mesh."""
self.nodes[node_id] = {
"endpoint": endpoint,
"capabilities": capabilities,
"status": "healthy",
"last_heartbeat": time.time()
}
def discover(self, capability):
"""Encontra nodes com uma capability especifica."""
return [
node_id for node_id, info in self.nodes.items()
if capability in info["capabilities"]
and info["status"] == "healthy"
]
def heartbeat(self, node_id):
"""Atualiza heartbeat de um node."""
if node_id in self.nodes:
self.nodes[node_id]["last_heartbeat"] = time.time()
# Uso
registry = MeshRegistry()
registry.register("marco-ai", "https://marco.fly.dev",
["knowledge", "governance", "metacognitive"])
registry.register("build-ai", "https://build.fly.dev",
["knowledge", "causal", "build"])
# Quem sabe sobre "knowledge"?
print(registry.discover("knowledge")) # ['marco-ai', 'build-ai']Heartbeats e health checks
Nodes do mesh precisam saber se seus pares estao vivos. Heartbeats sao mensagens periodicas "estou vivo". Se um node nao envia heartbeat por T segundos, e considerado down.
Diagrama
Heartbeat protocol:
Node A Registry Node B
| | |
|---HEALTH_CHECK(A)----->| |
| |---HEALTH_CHECK(B)---->|
| |<--HEALTH_OK-----------|
|<--registry updated-----| |
| | |
[... 30 segundos ...] | |
| | |
|---HEALTH_CHECK(A)----->| |
| |---HEALTH_CHECK(B)---->|
| | (timeout, sem resp) |
| | X (down!)
|<--NODE_DOWN(B)---------|
| |
Se Node B nao responde ao heartbeat por 3 tentativas
consecutivas, e marcado como "unhealthy" no registry.No harness.os
Este protocolo e o que o mesh do harness.os usara para comunicacao inter-node. O design combina conceitos de todas as aulas anteriores: formato de mensagem (camada de aplicacao), transporte confiavel (TCP), enderecamento (UUIDs como IPs), e roteamento (concern-based).
Resumo
- Formato de mensagem: header fixo (versao, tipo, flags, tamanho) + payload JSON
- Tipos de mensagem: KNOWLEDGE_SYNC, HEALTH_CHECK, SESSION_EVENT, ROUTE_UPDATE
- Service discovery: registry que mapeia node_id -> endpoint + capabilities
- Heartbeats: mensagens periodicas para detectar nodes fora do ar
- Combina request/response (queries) e pub/sub (eventos)
Exercicio pratico
Escreva a spec completa do protocolo HMP (Harness Mesh Protocol).
- Defina todos os tipos de mensagem e seus payloads JSON
- Especifique o comportamento de cada flag (REQUIRES_ACK, ENCRYPTED, etc.)
- Documente o fluxo de handshake entre dois nodes
- Defina timeouts e retries para cada tipo de mensagem
- Implemente
encode_message()edecode_message()completos
Verifique seu entendimento
Por que o header do protocolo tem tamanho fixo enquanto o payload e variavel?