Interfaces locais

O Agent oferece duas interfaces locais para o seu servidor pedir uma operação: uma por HTTP em loopback (interface A) e uma por spool de diretório (interface C). As duas fazem exatamente as mesmas operações — a diferença é o meio de transporte, e você escolhe pela capacidade da sua stack. Um servidor que tem um cliente HTTP usa a interface A; um servidor que só consegue escrever arquivos usa a interface C.

Nenhuma das duas expõe criptografia ao seu servidor: você manda JSON simples e recebe JSON simples. O trabalho de assinar, anexar jti e exp, enviar e repetir com backoff acontece dentro do Agent. É esse o ponto do componente.

Duas outras interfaces são planejadas

O desenho do Agent prevê quatro interfaces — além de A e C, uma CLI (interface B, chamar lootfy-agent no shell e ler o JSON do stdout) e uma biblioteca (interface D, importar o Agent no processo, sem processo separado). A v1 entrega apenas A e C, que cobrem os dois extremos: quem tem HTTP e quem só tem arquivo. B e D estão no backlog e ainda não existem. 📋 planejado

Interface A — HTTP em loopback

A interface A é um servidor HTTP que escuta em 127.0.0.1:8899 (configurável). O seu servidor faz um POST com o nome da operação e a entrada, e recebe o resultado. Serve qualquer stack com cliente HTTP — Node, PHP, Go, C++.

Sem autenticação, protegida só pelo loopback

Esta porta assina sob demanda e não tem autenticação — quem a alcança detém a autoridade do seu servidor na Lootfy. A defesa é o bind em loopback, conferido no boot. Nunca a exponha à internet, nunca a publique com -p. Uma senha aqui daria a impressão de proteger algo que só o isolamento de rede protege. Ver Segurança operacional.

POST /call — executar uma operação

O corpo é um JSON com três campos: operation (o nome da operação, obrigatório), input (os campos da operação) e um id opcional que serve de chave de idempotência.

curl -s http://127.0.0.1:8899/call \
  -H 'content-type: application/json' \
  -d '{
    "operation": "market.eligibility",
    "input": { "characterRef": "c1" },
    "id": "req-8f3a"
  }'

A resposta é sempre um JSON com o campo ok. Em sucesso, o resultado da plataforma vem dentro de data; o id, quando você o enviou, é ecoado de volta:

{ "ok": true, "id": "req-8f3a", "data": { "eligible": true } }

Quando a plataforma recusa a operação (uma regra de negócio, por exemplo), a resposta traz ok: false, a message da plataforma e o status HTTP original. A message já vem em pt-BR e pronta para exibir — o Agent a repassa exatamente como veio, e o seu jogo pode mostrá-la ao jogador sem reescrever nada:

{ "ok": false, "id": "req-8f3a", "message": "O personagem não está vinculado a uma conta.", "status": 409 }

200 no transporte, `ok` no resultado

Uma vez que a operação roda, a resposta do /call sai com HTTP 200 mesmo quando a plataforma recusou — o resultado do negócio está no campo ok, não no status HTTP do Agent. Os 4xx do próprio /call são reservados para erro de protocolo: 400 para JSON inválido, operação desconhecida ou corpo acima de 256 KB, e 404 para uma rota que não seja /call, /operations ou /health.

O cache por id

O campo id é o que torna o retry seguro. O Lua do servidor reenvia quando não tem certeza de que a primeira tentativa chegou — e frequentemente ele não tem como saber. Sem uma chave de idempotência, esse “não sei se deu certo” viraria uma segunda chamada de verdade à plataforma.

Quando você envia um id, o Agent guarda o resultado daquela chamada por 10 minutos. Uma segunda chamada com o mesmo id dentro dessa janela devolve o resultado guardado, sem tocar a plataforma de novo. Isso vale inclusive para recusas de negócio (4xx da plataforma): repetir daria a mesma recusa, então o Agent a guarda e evita o reenvio inútil a cada retry do Lua.

Use sempre um `id` estável no retry

Para que o cache funcione, o id precisa ser o mesmo entre a tentativa original e o retry. Um id novo a cada tentativa anula a idempotência. Escolha um identificador estável da ação (por exemplo, o id do anúncio ou da transação no seu lado).

GET /operations e GET /health

Dois endpoints de leitura completam a interface. GET /operations lista todas as operações disponíveis, cada uma com um resumo de uma linha:

curl -s http://127.0.0.1:8899/operations

GET /health confirma que o Agent está vivo e diz a versão:

{ "ok": true, "agent": "lootfy-agent/0.1.0" }

Interface C — spool de diretório

A interface C é para stacks que não têm cliente HTTP — o caso que a motivou é o Lua do TFS, onde db.* é a única saída de rede e uma fila em banco exigiria o Agent lendo o banco do parceiro, o que a premissa fundamental proíbe. Arquivo resolve os dois problemas de uma vez. Ela é ligada apontando LOOTFY_SPOOL_DIR para um diretório.

O diretório tem dois subdiretórios: o seu servidor escreve o pedido em outbox/ e lê a resposta em inbox/.

<spool>/outbox/<id>.json   ← o seu servidor escreve, o Agent consome
<spool>/inbox/<id>.json    ← o Agent escreve, o seu servidor consome

O pedido é um JSON com um id de correlação, a action (o nome da operação, igual ao operation da interface A) e os campos da operação no mesmo nível:

{ "id": "req-8f3a", "action": "market.eligibility", "characterRef": "c1" }

A resposta é escrita em inbox/<id>.json, com o mesmo id, um campo ok, e — em sucesso — os dados da plataforma planos, no nível de topo. Uma recusa traz ok: false, a message em pt-BR e o status:

{ "ok": true, "id": "req-8f3a", "eligible": true }

A resposta do spool é plana de propósito

Diferente da interface A, o spool não aninha os dados em data: quem os lê do outro lado é um parser de campo de topo escrito em Lua 5.1 sem biblioteca de JSON, e um nível a mais custaria um parser de verdade rodando sobre a thread do dispatcher. Se a plataforma devolver um campo chamado id (o id de um recurso criado, por exemplo), ele não sobrescreve o seu id de correlação: o Agent o preserva sob a chave resultId e mantém o id do pedido intacto.

Como o worker de spool trabalha

O worker varre o outbox/ a cada 200 ms e processa até 8 pedidos em voo ao mesmo tempo. Ao pegar um arquivo, ele o renomeia para reivindicá-lo — o rename é atômico no mesmo sistema de arquivos, então dois ticks nunca processam o mesmo arquivo duas vezes; quem perde a corrida simplesmente desiste. A resposta é escrita primeiro em um arquivo temporário e só então renomeada para o nome final, para que o seu servidor nunca leia um JSON pela metade no meio da escrita.

Escreva o arquivo de forma atômica também

Do seu lado, escreva o pedido em um arquivo temporário e o renomeie para outbox/<id>.json só quando estiver completo. Se o Agent pegar o arquivo enquanto você ainda o escreve, ele lê um JSON parcial. Rename atômico dos dois lados é o que mantém o canal confiável.

Qual interface usar

Interface A — HTTP

Escolha quando a sua stack tem um cliente HTTP (Node, PHP, Go, C++, um servidor que consegue fazer requisições). É a mais direta: um POST e uma resposta síncrona. Exige que o servidor e o Agent compartilhem o loopback da host.

Interface C — spool

Escolha quando a sua stack só consegue mexer em arquivo, ou quando fazer uma chamada de rede síncrona travaria o servidor. É a rota recomendada para TFS: io.popen seria síncrono na thread do dispatcher, e congelar o mundo a cada anúncio para esperar uma chamada de rede é inaceitável.

Próximo: catálogo de operações Todas as operações que o Agent expõe, o que cada uma faz e como autentica.