@acropole/skills 0.0.0-stage → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +181 -2
- package/agents/revisor-deploy.md +73 -0
- package/agents/revisor-documentacao.md +78 -0
- package/agents/revisor-orfeu.md +80 -0
- package/agents/revisor-trismegisto.md +81 -0
- package/bin/install.js +252 -0
- package/package.json +15 -4
- package/skills/acropole/SKILL.md +80 -0
- package/skills/acropole/references/arquitetura.md +174 -0
- package/skills/acropole/references/fluxos/app-novo.md +34 -0
- package/skills/acropole/references/fluxos/doctor.md +55 -0
- package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
- package/skills/acropole/references/fluxos/revisar.md +56 -0
- package/skills/acropole/references/fluxos/tela-nova.md +27 -0
- package/skills/acropole/scripts/doctor.mjs +439 -0
- package/skills/angular/SKILL.md +155 -0
- package/skills/angular/references/armadilhas.md +99 -0
- package/skills/angular/references/dados.md +251 -0
- package/skills/angular/references/estrutura.md +279 -0
- package/skills/angular/references/features.md +219 -0
- package/skills/angular/references/testes-build.md +257 -0
- package/skills/angular/scripts/checar.mjs +182 -0
- package/skills/angular/scripts/nucleo.mjs +227 -0
- package/skills/apollo/SKILL.md +226 -0
- package/skills/apollo/references/armadilhas.md +99 -0
- package/skills/apollo/references/envelope-erros.md +120 -0
- package/skills/apollo/references/estrutura-bootstrap.md +310 -0
- package/skills/apollo/references/schema-resolvers.md +183 -0
- package/skills/apollo/references/subscriptions.md +224 -0
- package/skills/apollo/references/testes-build.md +181 -0
- package/skills/apollo/scripts/checar.mjs +160 -0
- package/skills/apollo/scripts/nucleo.mjs +227 -0
- package/skills/docker/SKILL.md +102 -0
- package/skills/docker/references/modelos.md +251 -0
- package/skills/docker/references/porques.md +286 -0
- package/skills/documentacao/SKILL.md +146 -0
- package/skills/documentacao/references/checklist-coerencia.md +59 -0
- package/skills/documentacao/references/ligar-app-novo.md +107 -0
- package/skills/documentacao/references/modelo-especificacao.md +51 -0
- package/skills/documentacao/references/modelo-readme.md +75 -0
- package/skills/documentacao/scripts/checar.mjs +454 -0
- package/skills/documentacao/scripts/nucleo.mjs +227 -0
- package/skills/express/SKILL.md +156 -0
- package/skills/express/references/dados.md +180 -0
- package/skills/express/references/estrutura.md +157 -0
- package/skills/express/references/middlewares.md +227 -0
- package/skills/express/references/rotas-erros.md +286 -0
- package/skills/express/references/testes-deploy.md +154 -0
- package/skills/express/scripts/checar.mjs +115 -0
- package/skills/express/scripts/nucleo.mjs +227 -0
- package/skills/fastapi/SKILL.md +132 -0
- package/skills/fastapi/references/banco.md +197 -0
- package/skills/fastapi/references/estrutura.md +325 -0
- package/skills/fastapi/references/integracoes.md +145 -0
- package/skills/fastapi/references/rotas-erros.md +140 -0
- package/skills/fastapi/references/testes-deploy.md +190 -0
- package/skills/fastapi/scripts/checar.mjs +108 -0
- package/skills/fastapi/scripts/nucleo.mjs +227 -0
- package/skills/hefesto/SKILL.md +119 -0
- package/skills/hefesto/references/conceitos.md +131 -0
- package/skills/hefesto/references/diagnostico.md +70 -0
- package/skills/hefesto/references/fluxo.md +122 -0
- package/skills/hefesto/references/preparar-app.md +105 -0
- package/skills/orfeu/SKILL.md +162 -0
- package/skills/orfeu/references/angular-api.md +201 -0
- package/skills/orfeu/references/angular-armadilhas.md +116 -0
- package/skills/orfeu/references/angular-recipes.md +474 -0
- package/skills/orfeu/references/angular.md +212 -0
- package/skills/orfeu/references/diferencas.md +56 -0
- package/skills/orfeu/references/node-api.md +354 -0
- package/skills/orfeu/references/node-armadilhas.md +158 -0
- package/skills/orfeu/references/node-recipes.md +541 -0
- package/skills/orfeu/references/node.md +204 -0
- package/skills/orfeu/references/python-api.md +346 -0
- package/skills/orfeu/references/python-recipes.md +479 -0
- package/skills/orfeu/references/python.md +240 -0
- package/skills/orfeu/scripts/checar.mjs +126 -0
- package/skills/orfeu/scripts/nucleo.mjs +227 -0
- package/skills/trismegisto/SKILL.md +194 -0
- package/skills/trismegisto/references/angular-api.md +2788 -0
- package/skills/trismegisto/references/angular-exports.md +4020 -0
- package/skills/trismegisto/references/angular-recipes.md +1883 -0
- package/skills/trismegisto/references/angular-types.md +492 -0
- package/skills/trismegisto/references/angular.md +390 -0
- package/skills/trismegisto/references/catalogo/icones.json +912 -0
- package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
- package/skills/trismegisto/references/catalogo/tokens.json +240 -0
- package/skills/trismegisto/references/spine-api.md +1530 -0
- package/skills/trismegisto/references/spine-recipes.md +581 -0
- package/skills/trismegisto/references/spine.md +343 -0
- package/skills/trismegisto/scripts/checar.mjs +216 -0
- package/skills/trismegisto/scripts/nucleo.mjs +227 -0
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: apollo
|
|
3
|
+
description: "Servidores GraphQL com Apollo Server (Node/TypeScript) que fazem de gateway entre o front e os serviços REST/Python: schema SDL, resolvers que devolvem o envelope { status, message, data }, subscriptions graphql-ws com Redis, operation() do Orfeu por campo, testes e build. Use ao criar ou alterar query/mutation/subscription, resolver ou bootstrap do Apollo, ou quando o front precisa de um campo GraphQL novo. Middlewares, CORS e rotas REST do Express que hospeda o Apollo são da skill express; cliente Apollo e codegen no front, da angular."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# apollo — servidores GraphQL (Apollo Server)
|
|
7
|
+
|
|
8
|
+
O servidor GraphQL é um **gateway fino**: cada Query/Mutation chama um serviço de trás (REST, quase sempre
|
|
9
|
+
FastAPI) em nome do usuário e **devolve o envelope `{ status, message, data }` como veio**; cada Subscription
|
|
10
|
+
repassa o que o serviço de trás publica no Redis. Ele **não** fala com banco, não escreve texto de toast e não
|
|
11
|
+
tem regra de negócio — tudo isso mora no serviço de trás.
|
|
12
|
+
|
|
13
|
+
Skills vizinhas (não duplique o conteúdo delas):
|
|
14
|
+
|
|
15
|
+
| Assunto | Skill |
|
|
16
|
+
| --- | --- |
|
|
17
|
+
| `OrfeuClient`, `operation()`, níveis, auditoria, `orfeuHeaders`, trace | **orfeu** (aqui só o encaixe) |
|
|
18
|
+
| Express em si (middlewares, rotas REST, CORS, proxy) | **express** |
|
|
19
|
+
| O serviço Python chamado pelos módulos (envelope de origem, `detail`) | **fastapi** |
|
|
20
|
+
| Cliente Apollo no front, `unwrap`, codegen dos `.graphql` | **angular** |
|
|
21
|
+
|
|
22
|
+
Ainda não coberto: Strawberry (GraphQL em Python) e Fastify como servidor HTTP.
|
|
23
|
+
|
|
24
|
+
> **Antes de dar por terminado:** `node scripts/checar.mjs <arquivos alterados>` (caminho relativo a esta skill: instalada, fica em `~/.claude/skills/apollo/scripts/checar.mjs`; `--help` lista as regras, `--json` para máquina).
|
|
25
|
+
|
|
26
|
+
## Stack
|
|
27
|
+
|
|
28
|
+
Node 22, TypeScript ESM (`"type": "module"`), `@apollo/server` **5** + `@as-integrations/express4` (ou
|
|
29
|
+
`express5`), `express`, `cors`, `@graphql-tools/schema` (`makeExecutableSchema`), `graphql` 16, `graphql-ws` +
|
|
30
|
+
`ws`, `graphql-redis-subscriptions` + `ioredis`, `axios`, `lodash` (`merge`), `dotenv`, `@orfeu/node` **`^1.0.1`**
|
|
31
|
+
(a 1.0.0 aceitava usuário forjado no contexto das subscriptions).
|
|
32
|
+
Dev: `tsx` (watch), `typescript`, `vitest`, `cross-env`. Apollo Server 4 (`@apollo/server/express4`) ainda
|
|
33
|
+
aparece em servidores antigos — está fora de suporte; ao mexer, migre (ver
|
|
34
|
+
[references/testes-build.md](references/testes-build.md)).
|
|
35
|
+
|
|
36
|
+
## Estrutura
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
src/
|
|
40
|
+
index.ts dotenv (src/settings/environment/.env.<NODE_ENV>) → builder(process.env)
|
|
41
|
+
core/
|
|
42
|
+
builder.ts OrfeuClient → schema seguro → startup → HTTP + WS + Apollo → listen → sinais
|
|
43
|
+
response.ts Envelope, envelopeType, failure, forward
|
|
44
|
+
pubsub.ts RedisPubSub preguiçoso (getPubSub) + nomes de canal
|
|
45
|
+
context/context.types.ts GraphQLContext = OrfeuContext & { App, req }
|
|
46
|
+
schema/index.ts BASE_SCHEMA (scalars + type Query/Mutation/Subscription vazios)
|
|
47
|
+
schema/scalars.ts JSON e afins
|
|
48
|
+
server/{http,ws,apollo}.server.ts
|
|
49
|
+
web/
|
|
50
|
+
<dominio>/modules/index.ts cliente REST do domínio (axios + orfeuHeaders)
|
|
51
|
+
<dominio>/schemas/<recurso>/{queries,mutations,subscriptions}.ts + index.ts
|
|
52
|
+
<dominio>/schemas/index.ts junta os recursos do domínio
|
|
53
|
+
config/index.ts AppModules: um módulo por domínio → ctx.App.<Dominio>
|
|
54
|
+
config/schemas/schemas.extends.ts junta typeDefs e resolvers de todos os domínios
|
|
55
|
+
settings/environment/.env.* NÃO versionado (só .env.example)
|
|
56
|
+
tests/unit, tests/integration
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Domínios com os mesmos nomes do serviço de trás e do front. Detalhes e código do bootstrap:
|
|
60
|
+
[references/estrutura-bootstrap.md](references/estrutura-bootstrap.md).
|
|
61
|
+
|
|
62
|
+
## Regras essenciais
|
|
63
|
+
|
|
64
|
+
1. **Schema SDL em string TypeScript** (`` [`#graphql ...`] ``), não arquivos `.graphql` no servidor. Cada
|
|
65
|
+
arquivo exporta `schema: string[]` e `resolvers`; cada recurso **estende** os tipos raiz
|
|
66
|
+
(`extend type Query { ... }`). Arquivo sem campos exporta `schema: string[] = []` e `resolvers = {}`.
|
|
67
|
+
2. **Todo campo raiz é uma operação do Orfeu**: `operation(Level.<NÍVEL>, resolver)`. O mapa final passa por
|
|
68
|
+
`secureResolvers(orfeu, resolvers, { onForbidden })`, o schema por `assertSchemaSecured(schema)` e só
|
|
69
|
+
**depois** `await orfeu.startup()`. Campo sem `operation()` impede a subida — é o objetivo.
|
|
70
|
+
3. **Query/Mutation devolvem o envelope** (`<Nome>Response`, gerado por `envelopeType`). O resolver **não
|
|
71
|
+
lança**: `forward(() => ctx.App.X.metodo(args, ctx))` repassa o envelope do serviço e converte erro em
|
|
72
|
+
envelope de falha. `errors[]` do GraphQL fica para o que acontece antes do resolver (sintaxe, 401).
|
|
73
|
+
4. **Subscription não usa envelope** (é evento). Prefira evento magro (`{ id, kind }`) + o front busca com a
|
|
74
|
+
query, que reaplica permissão.
|
|
75
|
+
5. **Módulo recebe o `ctx` e manda `orfeuHeaders(ctx)`** em toda chamada ao serviço de trás (credencial,
|
|
76
|
+
`traceparent`, `x-route-id`, `x-client-id`). Nunca monte o header de token à mão.
|
|
77
|
+
6. **Mesmo `GRAPHQL_PATH`** no mount HTTP e no `WebSocketServer` — senão as subscriptions não conectam.
|
|
78
|
+
7. **Introspecção só com `GRAPHQL_INTROSPECTION=true`** (no `.env.local` de quem roda o codegen), nunca
|
|
79
|
+
derivada de `NODE_ENV`. `allowBatchedHttpRequests: true` sempre (o front envia em lote).
|
|
80
|
+
8. **Encerramento**: o `node` é PID 1 no container — trate `SIGTERM`/`SIGINT`: `orfeu.flushAudit()`,
|
|
81
|
+
`apollo.server.stop()` (o plugin de drain fecha HTTP e WS); sai com **0** ao completar e com **1** se
|
|
82
|
+
estourar o teto de 8 s.
|
|
83
|
+
9. Tudo que lê `process.env` em escopo de módulo quebra (ESM roda imports antes do `dotenv.config`): crie
|
|
84
|
+
clientes (Redis, axios) **dentro** do builder ou de forma preguiçosa.
|
|
85
|
+
10. **Orfeu fora do ar na subida: sobe negando** (padrão único). O servidor sobe, `/health` responde **503**
|
|
86
|
+
até o Orfeu conectar, toda operação não pública é negada e o `startup()` é tentado de novo com espera
|
|
87
|
+
crescente (5 s → 30 s). `OrfeuConfigError` derruba a subida. Nunca um modo que libera sem autorização
|
|
88
|
+
([references/estrutura-bootstrap.md](references/estrutura-bootstrap.md)).
|
|
89
|
+
11. **Contexto é do servidor, não do cliente**: nada de `ctx.orfeuUser` gravado à mão (usuário validado por
|
|
90
|
+
fora entra por `trustUser`) nem `connectionParams` espalhado no contexto do WebSocket.
|
|
91
|
+
12. **`compression()` antes do Apollo** em todo gateway, e `AUTH_TLS_VERIFY=false` (se existir) com aviso na
|
|
92
|
+
subida e `tls_verify: false` no `/health`. Padrão completo do app (pastas, portas, scripts, saúde):
|
|
93
|
+
skill `acropole` (`references/arquitetura.md`).
|
|
94
|
+
|
|
95
|
+
## Esqueleto de um recurso
|
|
96
|
+
|
|
97
|
+
```ts
|
|
98
|
+
// src/web/tags/schemas/tag/queries.ts
|
|
99
|
+
import { Level } from '@orfeu/node';
|
|
100
|
+
import { operation } from '@orfeu/node/apollo';
|
|
101
|
+
import type { GraphQLContext } from '../../../../core/context/context.types.js';
|
|
102
|
+
import { envelopeType, forward } from '../../../../core/response.js';
|
|
103
|
+
|
|
104
|
+
export const schema = [`#graphql
|
|
105
|
+
extend type Query {
|
|
106
|
+
listTags(search: String, offset: Int, limit: Int): TagsPageResponse!
|
|
107
|
+
getTag(tagId: ID!): TagResponse!
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
type Tag { tag_id: ID!, name: String!, created_at: String! }
|
|
111
|
+
type TagsPage { items: [Tag!]!, total: Int!, offset: Int! }
|
|
112
|
+
|
|
113
|
+
${envelopeType('TagsPageResponse', 'TagsPage')}
|
|
114
|
+
${envelopeType('TagResponse', 'Tag')}
|
|
115
|
+
`];
|
|
116
|
+
|
|
117
|
+
type ListArgs = { search?: string | null; offset?: number | null; limit?: number | null };
|
|
118
|
+
|
|
119
|
+
export const resolvers = {
|
|
120
|
+
Query: {
|
|
121
|
+
listTags: operation(Level.PRIVATE, (_: unknown, args: ListArgs, ctx: GraphQLContext) =>
|
|
122
|
+
forward(() => ctx.App.Tags.list(args, ctx))),
|
|
123
|
+
getTag: operation(Level.PRIVATE, (_: unknown, { tagId }: { tagId: string }, ctx: GraphQLContext) =>
|
|
124
|
+
forward(() => ctx.App.Tags.get(tagId, ctx))),
|
|
125
|
+
},
|
|
126
|
+
};
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
```ts
|
|
130
|
+
// src/web/tags/modules/index.ts
|
|
131
|
+
import axios, { type AxiosInstance } from 'axios';
|
|
132
|
+
import { orfeuHeaders, type OrfeuForwardSource } from '@orfeu/node';
|
|
133
|
+
|
|
134
|
+
export class TagsModule {
|
|
135
|
+
private http: AxiosInstance;
|
|
136
|
+
constructor(settings: NodeJS.ProcessEnv) {
|
|
137
|
+
this.http = axios.create({ baseURL: settings.PLATFORM_SERVICE_URL });
|
|
138
|
+
}
|
|
139
|
+
async list(args: { search?: string | null; offset?: number | null; limit?: number | null }, caller: OrfeuForwardSource) {
|
|
140
|
+
const params: Record<string, unknown> = { offset: args.offset ?? 0, limit: args.limit ?? 50 };
|
|
141
|
+
if (args.search) params.search = args.search; // filtro vazio não vai
|
|
142
|
+
const { data } = await this.http.get('/tags', { params, headers: orfeuHeaders(caller) });
|
|
143
|
+
return data; // o envelope do serviço, sem transformar
|
|
144
|
+
}
|
|
145
|
+
async get(tagId: string, caller: OrfeuForwardSource) {
|
|
146
|
+
const { data } = await this.http.get(`/tags/${encodeURIComponent(tagId)}`, { headers: orfeuHeaders(caller) });
|
|
147
|
+
return data;
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Depois: registrar o módulo em `web/config/index.ts` (+ `index.types.ts`) e o schema/resolvers em
|
|
153
|
+
`schemas.extends.ts`. Passo a passo, composição com `lodash/merge`, scalars e paginação:
|
|
154
|
+
[references/schema-resolvers.md](references/schema-resolvers.md).
|
|
155
|
+
|
|
156
|
+
## Níveis (encaixe; semântica completa na orfeu)
|
|
157
|
+
|
|
158
|
+
| Nível | Uso típico no gateway |
|
|
159
|
+
| --- | --- |
|
|
160
|
+
| `Level.PUBLIC` | health/diagnóstico sem usuário (`_health`) |
|
|
161
|
+
| `Level.OPTIONAL` | página pública que mostra mais para quem está logado (a regra fica no serviço) |
|
|
162
|
+
| `Level.PRIVATE` | padrão: usuário autenticado com permissão na operação |
|
|
163
|
+
| `Level.PROTECTED` | operação sensível que exige permissão explícita |
|
|
164
|
+
|
|
165
|
+
Id da operação: `query:<campo>`, `mutation:<campo>`, `subscription:<campo>`. Método: Query → `read`,
|
|
166
|
+
Subscription → `stream`, Mutation → `delete` se o campo começa com `delete|remove|destroy`, senão `write`.
|
|
167
|
+
**Nomeie mutations de remoção com esses prefixos.** Uma função só pode ser marcada uma vez — não reutilize
|
|
168
|
+
o mesmo resolver em dois campos.
|
|
169
|
+
|
|
170
|
+
## Envelope, erros e o front
|
|
171
|
+
|
|
172
|
+
`status` HTTP dentro do payload (2xx sucesso, 3xx atenção, 4xx/5xx erro), `message` é o texto do toast,
|
|
173
|
+
`data` o dado ou `null`. O front confere com `unwrap(result.campo)` e o cliente mostra o toast a partir do
|
|
174
|
+
envelope (mutation: sempre em falha, em sucesso se houver `message`; query: só em falha e nunca em 404;
|
|
175
|
+
subscription: nunca). Sem permissão (403) o `onForbidden` devolve envelope; sem credencial (401) é sempre
|
|
176
|
+
`GraphQLError` com `extensions.code = 401` (o front renova o token e reconecta). Tabela de falhas, 422 com
|
|
177
|
+
dados e mapeamento do `detail` do FastAPI: [references/envelope-erros.md](references/envelope-erros.md).
|
|
178
|
+
|
|
179
|
+
## Subscriptions
|
|
180
|
+
|
|
181
|
+
`graphql-ws` no mesmo servidor HTTP e path; contexto do WS montado por
|
|
182
|
+
`orfeuWsContext(orfeu, (ctx) => ({ App: appModules, ...wsContextParams(ctx) }))` — o `orfeuPlugin` só cobre
|
|
183
|
+
HTTP. O front manda em `connection_init` o token (`x-access-token`, na raiz e em `headers`), `routeId` e
|
|
184
|
+
`clientId`. **Nunca** `({ connectionParams }) => ({ ...connectionParams })`: o cliente escreve o que quiser
|
|
185
|
+
no `ctx`. O `extra` repassa só a allowlist `x-access-token`, `x-app-token`, `x-api-token`, `traceparent`,
|
|
186
|
+
`x-route-id`, `x-client-id`, e só valor string (`wsContextParams`, em `subscriptions.md`).
|
|
187
|
+
A autorização é **por campo** (preguiçosa), não na conexão. Canais Redis com prefixo do app; `resolve:
|
|
188
|
+
(payload) => payload` explícito. Filtro por escopo do usuário, dedup entre réplicas e eventos magros:
|
|
189
|
+
[references/subscriptions.md](references/subscriptions.md).
|
|
190
|
+
|
|
191
|
+
## Comandos
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
npm run dev # tsx watch, NODE_ENV=local (também start:local / start:homol)
|
|
195
|
+
npm run build # typecheck + esbuild --bundle → dist/index.js (um arquivo, em milissegundos)
|
|
196
|
+
npm run start:prod # node dist/index.js
|
|
197
|
+
npm run typecheck # tsc --noEmit
|
|
198
|
+
npx vitest run # unitários
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
Codegen é do **front** (introspecção do GraphQL local). Testes (resolver direto com `ctx` falso;
|
|
202
|
+
`executeOperation` com `orfeuPlugin` + servidor HTTP fake para conferir headers), Dockerfile multi-stage,
|
|
203
|
+
variáveis de ambiente e logs: [references/testes-build.md](references/testes-build.md).
|
|
204
|
+
|
|
205
|
+
## Armadilhas mais caras
|
|
206
|
+
|
|
207
|
+
- `process.env` lido no topo de módulo → Redis cai em `localhost:6379` em silêncio.
|
|
208
|
+
- Path do WS diferente do HTTP atrás do proxy reverso → subscription nunca conecta, sem erro claro.
|
|
209
|
+
- Contexto do WS sem `App` → `ctx.App` indefinido só nas subscriptions.
|
|
210
|
+
- `connectionParams` espalhado no contexto do WS → cliente forja chaves do `ctx` (com `@orfeu/node` 1.0.0,
|
|
211
|
+
até o usuário).
|
|
212
|
+
- Orfeu fora na subida com `/health` em 200 → o deploy vê saudável um gateway que nega tudo (o padrão é 503).
|
|
213
|
+
- Campo novo sem `operation()` → servidor não sobe (correto); campo reaproveitando função → erro de marca dupla.
|
|
214
|
+
- Esquecer `resolve` na subscription → `null` (o resolver padrão procura a chave com o nome do campo).
|
|
215
|
+
- Envelope sem `data` anulável ou sem `Response` no nome → codegen/`unwrap` do front quebram.
|
|
216
|
+
|
|
217
|
+
Lista completa com causa e correção: [references/armadilhas.md](references/armadilhas.md).
|
|
218
|
+
|
|
219
|
+
## Índice das referências
|
|
220
|
+
|
|
221
|
+
- [references/estrutura-bootstrap.md](references/estrutura-bootstrap.md) — builder, servidores HTTP/WS/Apollo, contexto, encerramento, `AppModules`.
|
|
222
|
+
- [references/schema-resolvers.md](references/schema-resolvers.md) — SDL, composição, scalars, resolvers, módulos REST, filtros e paginação, rotas REST fora do Apollo.
|
|
223
|
+
- [references/envelope-erros.md](references/envelope-erros.md) — `response.ts` completo, tabela de status, 401×403, 422 com dados, consumo no front.
|
|
224
|
+
- [references/subscriptions.md](references/subscriptions.md) — `graphql-ws`, `connectionParams`, Redis pub/sub, filtros por usuário, dedup.
|
|
225
|
+
- [references/testes-build.md](references/testes-build.md) — vitest, codegen, build, Docker, variáveis de ambiente, logs, migração Apollo 4→5.
|
|
226
|
+
- [references/armadilhas.md](references/armadilhas.md) — problemas reais e como evitar.
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# Armadilhas reais
|
|
2
|
+
|
|
3
|
+
Cada item aconteceu em servidor GraphQL de verdade. Formato: sintoma → causa → correção.
|
|
4
|
+
|
|
5
|
+
## Subida e ambiente
|
|
6
|
+
|
|
7
|
+
- **Redis sempre em `localhost:6379`, ignorando o `.env`** → o cliente era criado em escopo de módulo; em
|
|
8
|
+
ESM os imports estáticos rodam antes do `dotenv.config()` do `index.ts`, então `process.env.REDIS_*` estava
|
|
9
|
+
vazio → crie clientes dentro do builder ou de forma preguiçosa (`getPubSub()`); vale para axios, Redis e
|
|
10
|
+
qualquer módulo instanciado fora de função.
|
|
11
|
+
- **Processo de pé sem servir nada** → `try { await builder() } catch { console.error }` sem sair →
|
|
12
|
+
`process.exit(1)` na falha de subida (o orquestrador reinicia).
|
|
13
|
+
- **`.env.undefined`** → `dotenv.config({ path: \`.env.${process.env.NODE_ENV}\` })` sem padrão → `?? 'local'`.
|
|
14
|
+
- **Servidor ouvindo em porta aleatória no container** → o código lia uma variável de porta e o Dockerfile
|
|
15
|
+
definia outra (`listen({ port: undefined })` escolhe porta livre) → uma variável só (`PORT`), com padrão.
|
|
16
|
+
- **Deploy demora até o SIGKILL** → `node` é PID 1 e PID 1 sem handler ignora `SIGTERM`; ou `CMD` com `npm`,
|
|
17
|
+
que não repassa o sinal → `CMD ["node", "dist/index.js"]` + handler com `flushAudit()` e `apollo.server.stop()`
|
|
18
|
+
e teto de 8 s.
|
|
19
|
+
- **Auditoria perdida no encerramento** → saída sem `orfeu.flushAudit()`.
|
|
20
|
+
- **Encerramento que não termina** → handler fechando só `http.server.close()`: sockets WebSocket abertos
|
|
21
|
+
seguram o close até o teto → use `apollo.server.stop()` (o plugin de drain fecha o WS).
|
|
22
|
+
|
|
23
|
+
## Orfeu nos resolvers
|
|
24
|
+
|
|
25
|
+
- **"Operações sem nível declarado"/"sem registro no Orfeu" na subida** → campo raiz sem `operation()`, ou
|
|
26
|
+
resolver adicionado depois do `secureResolvers` → declare o nível; nunca contorne com operação coringa.
|
|
27
|
+
- **"esta função já foi declarada como operação"** → a mesma função usada em dois campos (a marca vai na
|
|
28
|
+
função) → função nova por campo: `campoB: operation(Level.PRIVATE, (...a) => fn(...a))`.
|
|
29
|
+
- **Operação registrada com método errado** → mutation de remoção sem prefixo `delete|remove|destroy`
|
|
30
|
+
(vira `write`) → renomeie ou passe `{ method }` no `operation()`.
|
|
31
|
+
- **`startup()` antes do `secureResolvers`** → operações não sincronizadas com o Argos.
|
|
32
|
+
- **"Modo degradado" que libera tudo quando o Argos está fora** → nunca; tente o `startup()` de novo em
|
|
33
|
+
segundo plano e mantenha negado até conectar.
|
|
34
|
+
- **Serviço "saudável" negando tudo** → subiu sem o Orfeu (startup em segundo plano) e o `/health` dizia
|
|
35
|
+
200 → enquanto o Orfeu não conecta, `/health` responde 503 (padrão: sobe negando, nova tentativa 5 s → 30 s).
|
|
36
|
+
- **Loop de restart com o Argos fora** → gateway que cai (`exit 1`) quando o `startup()` falha → suba negando
|
|
37
|
+
e tente de novo; só `OrfeuConfigError` (configuração errada) derruba a subida.
|
|
38
|
+
- **Encerramento por teto saindo com 0** → o orquestrador não distingue drenagem completa de travamento →
|
|
39
|
+
`exit(0)` ao completar, `exit(1)` no teto de 8 s.
|
|
40
|
+
- **401 em todo campo depois de atualizar o `@orfeu/node` para 1.0.1** → o `context()` gravava
|
|
41
|
+
`orfeuUser` à mão → `trustUser(ctx, claims)`, ou deixe o `orfeuPlugin` capturar a credencial.
|
|
42
|
+
- **Validação de token duplicada no `context()`** (montando `{ token, user }` à mão) → diverge do guard e
|
|
43
|
+
gasta chamada → deixe o `orfeuPlugin` + `secureResolvers` decidirem; use `ctx.orfeuUser`.
|
|
44
|
+
|
|
45
|
+
## Serviço de trás
|
|
46
|
+
|
|
47
|
+
- **Ação aparece partida em dois traces na auditoria** → o módulo mandava só o token, sem `traceparent` →
|
|
48
|
+
`orfeuHeaders(ctx)` em toda chamada.
|
|
49
|
+
- **Mensagem amigável do serviço ignorada no toast** → `failure` lia `detail` antes de `message` → `message`
|
|
50
|
+
primeiro.
|
|
51
|
+
- **422 com a lista de problemas virou `data: null`** → axios lança em 4xx → `validateStatus` aceitando 422
|
|
52
|
+
naquela chamada.
|
|
53
|
+
- **Verificação TLS desligada no agente HTTP** (`rejectUnauthorized: false`) para "funcionar em homologação"
|
|
54
|
+
e esquecida → configure `NODE_EXTRA_CA_CERTS`.
|
|
55
|
+
- **Agente/opções perdidos em subclasse do cliente REST** → subclasse recriava o `axios.create` sem o
|
|
56
|
+
`httpsAgent` da base → um `axios.create` só, configurado num lugar.
|
|
57
|
+
- **Dois mecanismos de trace** (header próprio `x-trace-id` + `traceparent` do Orfeu) → manter só o do Orfeu.
|
|
58
|
+
- **Resposta enorme lenta** (dezenas de MB) → sem `compression()` e com o mesmo sub-objeto repetido em cada
|
|
59
|
+
item → `compression()` antes do Apollo e deduplicar no payload (lista de entidades + referência por chave).
|
|
60
|
+
|
|
61
|
+
## Schema
|
|
62
|
+
|
|
63
|
+
- **Tipo raiz vazio** (`type Mutation` sem campos) → schema inválido → declare só os tipos raiz usados; não
|
|
64
|
+
crie `_noop` só para tapar.
|
|
65
|
+
- **Tipo duplicado** → mesmo `envelopeType('X', ...)` declarado em dois arquivos → um lugar só (domínio
|
|
66
|
+
`shared/` para os reaproveitados).
|
|
67
|
+
- **`merge(a, b)` mutando o mapa de outro domínio** → sempre `merge({}, ...)`.
|
|
68
|
+
- **Resolver de campo fazendo chamada remota** → N+1 → pedir o dado montado ao serviço.
|
|
69
|
+
|
|
70
|
+
## Subscriptions
|
|
71
|
+
|
|
72
|
+
- **Cliente nunca conecta atrás do proxy** → path do `WebSocketServer` diferente do mount HTTP, ou proxy sem
|
|
73
|
+
upgrade de WebSocket naquele path → mesmo `GRAPHQL_PATH` nos dois.
|
|
74
|
+
- **Toda subscription privada negada** → contexto do WS sem `orfeuWsContext` (o `orfeuPlugin` só roda no HTTP).
|
|
75
|
+
- **`ctx.App` indefinido só nas subscriptions** → `App` não passado no `extra` do `orfeuWsContext`.
|
|
76
|
+
- **Cliente sem token passando em subscription `private`/`protected`** → `extra` devolvendo
|
|
77
|
+
`{ ...connectionParams }`: o cliente escrevia `orfeuUser` no `connection_init` e o `@orfeu/node` 1.0.0
|
|
78
|
+
confiava → `^1.0.1` e `extra` com allowlist de headers (`x-access-token`, `x-app-token`, `x-api-token`,
|
|
79
|
+
`traceparent`, `x-route-id`, `x-client-id`, só string) — `subscriptions.md`. Mesmo na 1.0.1, o spread deixa
|
|
80
|
+
qualquer outra chave do cliente chegar ao `ctx` dos resolvers.
|
|
81
|
+
- **Evento chega `null`** → falta `resolve: (payload) => payload` (o padrão procura a chave com o nome do campo).
|
|
82
|
+
- **Evento publicado e nunca recebido** → `REDIS_DB` ou prefixo de canal diferente entre publicador e gateway.
|
|
83
|
+
- **Rascunho/dado restrito vazando pelo WS** → evento com o dado inteiro para todos os inscritos → evento
|
|
84
|
+
magro `{ id, kind }` + refetch pela query, ou filtro por escopo no `subscribe`.
|
|
85
|
+
- **Inscrição Redis presa depois que o cliente sai** → iterator filtrado sem repassar `return`/`throw`.
|
|
86
|
+
- **Evento duplicado** com mais de uma réplica publicando → `event_id` + `SET NX` no gateway.
|
|
87
|
+
- **Console inundado com Redis fora em dev** → listener de `error` com log limitado.
|
|
88
|
+
|
|
89
|
+
## Tipagem e build
|
|
90
|
+
|
|
91
|
+
- **`ctx: any` em todo resolver** → esconde `ctx.App` ausente e argumento renomeado → `GraphQLContext` e
|
|
92
|
+
args tipados.
|
|
93
|
+
- **Dois tipos `WebSocketServer` incompatíveis** sob NodeNext (`@types/ws` resolvido como import e require)
|
|
94
|
+
→ `as any` só na chamada do `useServer`, com comentário.
|
|
95
|
+
- **Build com esbuild passando com erro de tipo** → esbuild não checa tipos → `tsc --noEmit` no fluxo.
|
|
96
|
+
- **Alias `src/...` quebrando em produção** → `tsc` não reescreve paths → imports relativos com `.js`, ou
|
|
97
|
+
bundle com esbuild.
|
|
98
|
+
- **Documentação citando script que não existe mais** → ao remover ferramenta (ex.: script de impressão de
|
|
99
|
+
schema), atualize o README no mesmo trabalho.
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
# Envelope e erros
|
|
2
|
+
|
|
3
|
+
## Contrato
|
|
4
|
+
|
|
5
|
+
Toda Query e Mutation devolve:
|
|
6
|
+
|
|
7
|
+
```graphql
|
|
8
|
+
type OrderResponse { status: Int!, message: String!, data: Order }
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
| Campo | Significado |
|
|
12
|
+
| --- | --- |
|
|
13
|
+
| `status` | código HTTP **dentro do payload**: 2xx sucesso, 3xx atenção, 4xx/5xx erro. A resposta HTTP do GraphQL continua 200. |
|
|
14
|
+
| `message` | texto do toast, escrito pelo **serviço de trás** (o gateway não escreve texto de negócio). Pode ser `''`. |
|
|
15
|
+
| `data` | o dado, ou `null` em falha. Pode vir preenchido junto com 4xx quando o dado explica a falha (ex.: 422 com achados de validação). |
|
|
16
|
+
|
|
17
|
+
Subscription **não** usa envelope.
|
|
18
|
+
|
|
19
|
+
## `src/core/response.ts`
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
import type { AxiosError } from 'axios';
|
|
23
|
+
|
|
24
|
+
export interface Envelope<T> { status: number; message: string; data: T | null; }
|
|
25
|
+
|
|
26
|
+
/** SDL: envelopeType('OrderResponse', 'Order') → type OrderResponse { status: Int!, message: String!, data: Order } */
|
|
27
|
+
export const envelopeType = (name: string, dataType: string): string =>
|
|
28
|
+
`type ${name} { status: Int!, message: String!, data: ${dataType} }`;
|
|
29
|
+
|
|
30
|
+
/** `detail` do FastAPI: texto (HTTPException) ou lista de erros do pydantic (422). */
|
|
31
|
+
const detailText = (detail: unknown): string | undefined => {
|
|
32
|
+
if (typeof detail === 'string') return detail;
|
|
33
|
+
if (Array.isArray(detail)) {
|
|
34
|
+
const msgs = detail.map((d) => (d as { msg?: string })?.msg).filter(Boolean);
|
|
35
|
+
return msgs.length ? msgs.join('; ') : undefined;
|
|
36
|
+
}
|
|
37
|
+
return undefined;
|
|
38
|
+
};
|
|
39
|
+
|
|
40
|
+
/** Erro (axios ou não) → envelope de falha com o status e a mensagem real do serviço. */
|
|
41
|
+
export function failure<T = never>(err: unknown): Envelope<T> {
|
|
42
|
+
const e = err as AxiosError<{ detail?: unknown; message?: string }>;
|
|
43
|
+
const response = e?.response;
|
|
44
|
+
if (e?.isAxiosError && !response) {
|
|
45
|
+
return { status: 503, message: 'Serviço indisponível. Tente novamente em instantes.', data: null };
|
|
46
|
+
}
|
|
47
|
+
if (response) {
|
|
48
|
+
const message = response.data?.message || detailText(response.data?.detail) || e.message;
|
|
49
|
+
return { status: response.status, message, data: null };
|
|
50
|
+
}
|
|
51
|
+
console.error('[graphql] erro inesperado no resolver:', err);
|
|
52
|
+
return { status: 500, message: err instanceof Error && err.message ? err.message : 'Erro inesperado no serviço.', data: null };
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** Repassa o envelope do serviço; erro HTTP ou inesperado vira envelope de falha. */
|
|
56
|
+
export async function forward<T>(run: () => Promise<Partial<Envelope<T>> | null | undefined>): Promise<Envelope<T>> {
|
|
57
|
+
try {
|
|
58
|
+
const res = (await run()) ?? {};
|
|
59
|
+
return { status: typeof res.status === 'number' ? res.status : 200, message: res.message ?? '', data: res.data ?? null };
|
|
60
|
+
} catch (err) {
|
|
61
|
+
return failure<T>(err);
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
- Ordem da mensagem de falha: `message` do envelope (serviço que já responde no padrão) → `detail` do
|
|
67
|
+
FastAPI cru → mensagem do axios. Coloque `message` primeiro: com `detail` primeiro, o texto amigável do
|
|
68
|
+
serviço é ignorado quando os dois vêm.
|
|
69
|
+
- A mensagem de 503 pode citar o nome do serviço do app ("Serviço de pedidos indisponível...").
|
|
70
|
+
- `forward` assume que o serviço já devolve `{ status, message, data }`. Se um serviço devolve o dado cru,
|
|
71
|
+
adapte **no módulo** (`return { status: 200, message: '', data }`), não no resolver.
|
|
72
|
+
|
|
73
|
+
## Tabela de situações
|
|
74
|
+
|
|
75
|
+
| Situação | O que o cliente recebe | Quem produz |
|
|
76
|
+
| --- | --- | --- |
|
|
77
|
+
| Sucesso | `{ status: 2xx, message, data }` | serviço → `forward` |
|
|
78
|
+
| Erro de negócio / validação | `{ status: 4xx, message, data: null }` | serviço (HTTP 4xx) → `failure` |
|
|
79
|
+
| 422 com dados úteis | `{ status: 422, message, data: { findings: [...] } }` | módulo com `validateStatus` → `forward` |
|
|
80
|
+
| Serviço fora do ar / timeout de rede | `{ status: 503, ... }` | `failure` (axios sem `response`) |
|
|
81
|
+
| Exceção no próprio gateway | `{ status: 500, ... }` + `console.error` | `failure` |
|
|
82
|
+
| Autenticado sem permissão (403) | `{ status: 403, message, data: null }` | `onForbidden` do `secureResolvers` |
|
|
83
|
+
| Sem credencial / token inválido (401) | `errors[]` com `extensions: { code: 401, status: 401, reason: 'UNAUTHENTICATED', operation }` e campo `null` | Orfeu (sempre `GraphQLError`) |
|
|
84
|
+
| Subscription negada (401/403) | `errors[]` no evento / encerramento da inscrição | Orfeu |
|
|
85
|
+
| Erro de sintaxe/validação da operação | `errors[]` (400) | Apollo |
|
|
86
|
+
|
|
87
|
+
O 401 é erro e não envelope **de propósito**: o cliente do front usa o código para renovar o token e
|
|
88
|
+
reconectar o socket, não para mostrar toast.
|
|
89
|
+
|
|
90
|
+
## Auditoria do resultado
|
|
91
|
+
|
|
92
|
+
O Orfeu audita o resultado pelo envelope (`envelopeOutcome`): resultado com `status >= 400` é gravado como
|
|
93
|
+
falha, com a `message`. Por isso o resolver **devolve** o erro em vez de lançar — e por isso o envelope de
|
|
94
|
+
falha precisa do `status` real. Detalhes: **orfeu**.
|
|
95
|
+
|
|
96
|
+
## Consumo no front (resumo; detalhes na angular)
|
|
97
|
+
|
|
98
|
+
```graphql
|
|
99
|
+
mutation CreateOrder($input: CreateOrderInput!) {
|
|
100
|
+
createOrder(input: $input) { status message data { ...OrderFields } }
|
|
101
|
+
}
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
```ts
|
|
105
|
+
const order = unwrap((await this.gql.mutate(CreateOrderDocument, { input })).createOrder);
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
- Toda operação pede `status message data { ... }`.
|
|
109
|
+
- `unwrap` lança `GraphqlEnvelopeError(status, message)` quando o envelope não veio (campo `null`) ou o
|
|
110
|
+
status não é 2xx; a tela decide pelo `status` (403 sem acesso, 404 vazio, 5xx tentar de novo).
|
|
111
|
+
- O cliente mostra o toast a partir do envelope: mutation sempre em falha e em sucesso se houver `message`;
|
|
112
|
+
query só em falha e nunca em 404; subscription nunca. Operação que trata a falha sozinha usa
|
|
113
|
+
`context: { silenceEnvelope: true }`.
|
|
114
|
+
- Consequência para o servidor: **mensagem de sucesso de mutation é toast** — mande texto curto ou `''`;
|
|
115
|
+
não devolva 404 em query quando a tela deveria avisar erro.
|
|
116
|
+
|
|
117
|
+
## Status em texto (legado)
|
|
118
|
+
|
|
119
|
+
Resolvers antigos devolvem `status: 'error' | 'failed'`. O front aceita, mas o padrão é numérico — ao tocar
|
|
120
|
+
num resolver assim, migre para `Int`.
|