@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,224 @@
|
|
|
1
|
+
# Subscriptions (graphql-ws + Redis)
|
|
2
|
+
|
|
3
|
+
## Fluxo
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
serviço de trás grava → publica no Redis (canal <prefixo>:<recurso>[:<escopo>])
|
|
7
|
+
→ RedisPubSub do gateway → resolver Subscription → graphql-ws → navegador
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
O gateway **não gera eventos**: só repassa o que o serviço de trás publica. Isso permite várias réplicas do
|
|
11
|
+
gateway e mantém a regra de negócio num lugar só.
|
|
12
|
+
|
|
13
|
+
## Servidor WebSocket
|
|
14
|
+
|
|
15
|
+
- `graphql-ws` (protocolo `graphql-transport-ws`) sobre `ws`, no **mesmo** `http.Server` e no **mesmo path**
|
|
16
|
+
do HTTP (`GRAPHQL_PATH`). O proxy reverso precisa encaminhar o upgrade de WebSocket nesse path.
|
|
17
|
+
- O `graphql-ws` executa o schema **sem os plugins do Apollo**: o contexto vem do
|
|
18
|
+
`orfeuWsContext(orfeu, extra)`, que faz no WS o que o `orfeuPlugin` faz no HTTP (credencial, trace,
|
|
19
|
+
routeId/clientId). Sem ele toda subscription não pública é negada.
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
// App disponível também nas subscriptions; do connectionParams, só a allowlist (abaixo)
|
|
23
|
+
const wsContext = orfeuWsContext(orfeu, (ctx) => ({ App: appMods, ...wsContextParams(ctx) }));
|
|
24
|
+
const ws = new WsServer(http.server, schema, wsContext, graphqlPath);
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
- O `apollo.server.stop()` chama `ws.serverCleanup.dispose()` pelo plugin `drainServer` — fecha os sockets
|
|
28
|
+
no encerramento.
|
|
29
|
+
- Não rejeite a conexão sem token no `onConnect`: subscriptions `OPTIONAL` (páginas públicas) usam o mesmo
|
|
30
|
+
socket. A autorização acontece **por campo**, a cada `subscribe`.
|
|
31
|
+
|
|
32
|
+
## `connectionParams` (o que o front manda no `connection_init`)
|
|
33
|
+
|
|
34
|
+
```json
|
|
35
|
+
{
|
|
36
|
+
"x-access-token": "<token>",
|
|
37
|
+
"routeId": "<id da rota da página>",
|
|
38
|
+
"clientId": "<id do app no Argos>",
|
|
39
|
+
"headers": { "x-access-token": "<token>" }
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
- Credencial lida pelo `orfeuWsContext` na raiz **ou** em `headers` (`x-access-token` → `x-app-token` →
|
|
44
|
+
`x-api-token`). O cliente padrão do front manda nos dois lugares; um servidor novo não precisa ler os dois
|
|
45
|
+
à mão.
|
|
46
|
+
- `routeId`/`clientId` vão para a auditoria de cada evento. Também aceitos como `x-route-id`/`x-client-id`.
|
|
47
|
+
- `traceparent` pode vir em `connectionParams`; sem ele cada inscrição abre trace novo.
|
|
48
|
+
- Os parâmetros são lidos **uma vez por conexão**. Token renovado só entra na próxima conexão — o front
|
|
49
|
+
derruba e recria o socket em 401/4401/4403 e quando a aba volta de segundo plano longo.
|
|
50
|
+
|
|
51
|
+
### Nunca espalhe o `connectionParams` no contexto
|
|
52
|
+
|
|
53
|
+
`({ connectionParams }) => ({ ...connectionParams })` no `extra` do `orfeuWsContext` (ou no `context` do
|
|
54
|
+
`useServer`) põe no `ctx` **qualquer chave que o cliente escrever** no `connection_init`. Com o
|
|
55
|
+
`@orfeu/node` 1.0.0 isso era uma falha de autorização: um cliente sem token mandava
|
|
56
|
+
`orfeuUser: { groups: [...] }` e passava nas operações `private`/`protected`. A 1.0.1 descarta as chaves
|
|
57
|
+
reservadas do Orfeu (`ORFEU_RESERVED_CONTEXT_KEYS`), mas qualquer outra chave (`App`, `user`, `tenantId`, um
|
|
58
|
+
nome que o seu resolver lê) continua forjável. Exija `@orfeu/node` `^1.0.1` **e** repasse só uma allowlist,
|
|
59
|
+
e só valor string:
|
|
60
|
+
|
|
61
|
+
```ts
|
|
62
|
+
// src/core/context/ws-context.ts
|
|
63
|
+
// Do connectionParams (graphql-ws) só passam para o contexto os headers de credencial e de rastreio.
|
|
64
|
+
// O orfeuWsContext já lê credencial, traceparent e correlação sozinho; esta lista não deixa o cliente
|
|
65
|
+
// escrever chave nenhuma além dessas no ctx dos resolvers.
|
|
66
|
+
const WS_ALLOWED_PARAMS = [
|
|
67
|
+
'x-access-token', 'x-app-token', 'x-api-token', // credencial
|
|
68
|
+
'traceparent', 'x-route-id', 'x-client-id', // rastreio e correlação
|
|
69
|
+
] as const;
|
|
70
|
+
|
|
71
|
+
export type WsAllowedParam = (typeof WS_ALLOWED_PARAMS)[number];
|
|
72
|
+
|
|
73
|
+
export function wsContextParams(
|
|
74
|
+
{ connectionParams }: { connectionParams?: Record<string, unknown> },
|
|
75
|
+
): Partial<Record<WsAllowedParam, string>> {
|
|
76
|
+
const out: Partial<Record<WsAllowedParam, string>> = {};
|
|
77
|
+
if (!connectionParams || typeof connectionParams !== 'object') return out;
|
|
78
|
+
const headers = connectionParams.headers as Record<string, unknown> | undefined;
|
|
79
|
+
for (const key of WS_ALLOWED_PARAMS) {
|
|
80
|
+
// mesma ordem do Orfeu: raiz do connectionParams primeiro, depois connectionParams.headers
|
|
81
|
+
const value = connectionParams[key] ?? (headers && typeof headers === 'object' ? headers[key] : undefined);
|
|
82
|
+
if (typeof value === 'string') out[key] = value; // objeto, número, array: descartado
|
|
83
|
+
}
|
|
84
|
+
return out;
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
- Teste unitário da função: chave fora da lista (`orfeuUser`, `user`, `App`) não passa; valor não string
|
|
89
|
+
não passa; `headers` é lido quando a raiz não tem a chave.
|
|
90
|
+
- O verificador da skill (regra `ws-connection-params-espalhado`) acusa o spread de `connectionParams` no
|
|
91
|
+
argumento do `orfeuWsContext`/`useServer` e em função de contexto de WS.
|
|
92
|
+
- Precisa de um usuário que o app validou por fora no contexto do WS? Não grave `orfeuUser`: use
|
|
93
|
+
`trustUser` (skill `orfeu` em `references/node-recipes.md` §4).
|
|
94
|
+
|
|
95
|
+
## PubSub no Redis (preguiçoso)
|
|
96
|
+
|
|
97
|
+
```ts
|
|
98
|
+
// src/core/pubsub.ts
|
|
99
|
+
import { RedisPubSub } from 'graphql-redis-subscriptions';
|
|
100
|
+
import { Redis } from 'ioredis';
|
|
101
|
+
|
|
102
|
+
function options() {
|
|
103
|
+
return {
|
|
104
|
+
host: process.env.REDIS_HOST,
|
|
105
|
+
port: Number(process.env.REDIS_PORT ?? 6379),
|
|
106
|
+
password: process.env.REDIS_PASSWORD || undefined,
|
|
107
|
+
db: Number(process.env.REDIS_DB ?? 0), // o MESMO db do serviço que publica
|
|
108
|
+
retryStrategy: (attempt: number) => Math.min(attempt * 200, 5000), // retry infinito, frequência limitada
|
|
109
|
+
};
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
function throttleErrors(client: Redis, label: string) {
|
|
113
|
+
let last = 0;
|
|
114
|
+
client.on('error', (err) => {
|
|
115
|
+
if (Date.now() - last > 30_000) { console.error(`[pubsub:${label}] Redis: ${err.message}`); last = Date.now(); }
|
|
116
|
+
});
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
let instance: RedisPubSub | undefined;
|
|
120
|
+
/** Criado no primeiro uso: em escopo de módulo leria process.env antes do dotenv.config(). */
|
|
121
|
+
export function getPubSub(): RedisPubSub {
|
|
122
|
+
if (!instance) {
|
|
123
|
+
const publisher = new Redis(options());
|
|
124
|
+
const subscriber = new Redis(options());
|
|
125
|
+
throttleErrors(publisher, 'publisher');
|
|
126
|
+
throttleErrors(subscriber, 'subscriber');
|
|
127
|
+
instance = new RedisPubSub({ publisher, subscriber });
|
|
128
|
+
}
|
|
129
|
+
return instance;
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
export const channel = (name: string) => `${process.env.REDIS_CHANNEL_PREFIX ?? 'meuapp:'}${name}`;
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
- Instância Redis compartilhada → **prefixo de canal** por app, igual no publicador e no gateway.
|
|
136
|
+
- `REDIS_DB` diferente entre publicador e gateway = eventos que nunca chegam, sem erro. Redis Cluster só tem
|
|
137
|
+
o db 0.
|
|
138
|
+
- Para Cluster: `new Redis.Cluster(nodes, { redisOptions: { password } })` escolhido por variável
|
|
139
|
+
(`REDIS_CLUSTER=true`, `REDIS_HOSTS=h1:p,h2:p`).
|
|
140
|
+
- Sem o listener de `error`, Redis fora do ar em dev inunda o console com "Unhandled error event".
|
|
141
|
+
|
|
142
|
+
## Resolver de Subscription
|
|
143
|
+
|
|
144
|
+
```ts
|
|
145
|
+
import { Level } from '@orfeu/node';
|
|
146
|
+
import { operation } from '@orfeu/node/apollo';
|
|
147
|
+
import { channel, getPubSub } from '../../../../core/pubsub.js';
|
|
148
|
+
|
|
149
|
+
export const schema = [`#graphql
|
|
150
|
+
type OrderEvent { id: ID!, kind: String! } # kind: changed | removed
|
|
151
|
+
extend type Subscription { orderChanged: OrderEvent! }
|
|
152
|
+
`];
|
|
153
|
+
|
|
154
|
+
export const resolvers = {
|
|
155
|
+
Subscription: {
|
|
156
|
+
orderChanged: operation(Level.PRIVATE, {
|
|
157
|
+
subscribe: () => getPubSub().asyncIterableIterator(channel('orders')),
|
|
158
|
+
resolve: (payload: { id: string; kind: string }) => ({ id: payload.id, kind: payload.kind }),
|
|
159
|
+
}),
|
|
160
|
+
},
|
|
161
|
+
};
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
- `operation()` no objeto `{ subscribe, resolve }` (a marca vai na função `subscribe`).
|
|
165
|
+
- **`resolve` explícito**: sem ele o resolver padrão procura `payload.orderChanged` e devolve `null`.
|
|
166
|
+
- `asyncIterableIterator` (graphql-subscriptions 3); `asyncIterator` é o nome antigo e ainda existe no
|
|
167
|
+
`graphql-redis-subscriptions` 2.7.
|
|
168
|
+
- Canal parametrizado por argumento: `subscribe: (_, { input }) => getPubSub().asyncIterableIterator(channel(\`map:${input?.environment ?? 'default'}\`))`.
|
|
169
|
+
- Subscription negada é sempre `GraphQLError` (sem envelope).
|
|
170
|
+
|
|
171
|
+
## Evento magro + refetch (recomendado)
|
|
172
|
+
|
|
173
|
+
O evento leva só `{ id, kind }`; quem recebe busca o item pela query (`getOrder(id)`), que reaplica permissão
|
|
174
|
+
e regras de visibilidade. Assim um rascunho nunca vaza pelo WebSocket. Evento "gordo" (o dado inteiro) só
|
|
175
|
+
quando todos os inscritos podem ver tudo e o volume justifica (painéis de monitoramento).
|
|
176
|
+
|
|
177
|
+
## Filtro por escopo do usuário
|
|
178
|
+
|
|
179
|
+
Quando cada usuário só pode receber parte dos eventos, pergunte o escopo ao serviço de trás **uma vez** no
|
|
180
|
+
`subscribe` e filtre o iterator:
|
|
181
|
+
|
|
182
|
+
```ts
|
|
183
|
+
function filtered<T>(it: AsyncIterator<T>, accept: (v: T) => boolean): AsyncIterableIterator<T> {
|
|
184
|
+
return {
|
|
185
|
+
async next() { for (;;) { const r = await it.next(); if (r.done || accept(r.value)) return r; } },
|
|
186
|
+
return: (v?: any) => (it.return ? it.return(v) : Promise.resolve({ done: true, value: v })),
|
|
187
|
+
throw: (e?: any) => (it.throw ? it.throw(e) : Promise.reject(e)),
|
|
188
|
+
[Symbol.asyncIterator]() { return this; },
|
|
189
|
+
};
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
orderChangedMine: operation(Level.PRIVATE, {
|
|
193
|
+
subscribe: async (_: unknown, __: unknown, ctx: GraphQLContext) => {
|
|
194
|
+
const scope = await ctx.App.Orders.watchScope(ctx); // GET autenticado com orfeuHeaders(ctx)
|
|
195
|
+
const teams = new Set(scope.teamIds);
|
|
196
|
+
return filtered(getPubSub().asyncIterableIterator<OrderPayload>(channel('orders:manage')),
|
|
197
|
+
(e) => scope.unrestricted || (!!e.teamId && teams.has(e.teamId)));
|
|
198
|
+
},
|
|
199
|
+
resolve: (p: OrderPayload) => ({ id: p.id, kind: p.kind }),
|
|
200
|
+
}),
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
- `return`/`throw` repassados ao iterator de baixo — senão a inscrição no Redis não é liberada quando o
|
|
204
|
+
cliente cancela.
|
|
205
|
+
- Mudança de escopo (usuário trocou de time) vale na próxima conexão.
|
|
206
|
+
- Inclua o escopo anterior no payload (`previousTeamId`) para quem perdeu acesso saber que o item saiu.
|
|
207
|
+
|
|
208
|
+
## Dedup entre réplicas
|
|
209
|
+
|
|
210
|
+
Se mais de uma instância do serviço de trás pode publicar o mesmo evento, mande `event_id` no payload e
|
|
211
|
+
deduplique no gateway com `SET NX`:
|
|
212
|
+
|
|
213
|
+
```ts
|
|
214
|
+
const seen = await redis.set(`{pub}:seen:${eventId}`, '1', 'NX', 'PX', 30_000);
|
|
215
|
+
if (seen === 'OK') return result; // primeira vez: entrega; senão, descarta e lê o próximo
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
Evento sem `event_id` passa direto.
|
|
219
|
+
|
|
220
|
+
## Reconexão
|
|
221
|
+
|
|
222
|
+
O `graphql-ws` do front reassina sozinho, mas eventos publicados durante a queda **não** são reenviados.
|
|
223
|
+
O front ressincroniza (refaz a query) quando o socket reconecta. Do lado do servidor: toda subscription deve
|
|
224
|
+
ter uma query equivalente que devolva o estado atual.
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
# Codegen, testes, build, Docker, ambiente e logs
|
|
2
|
+
|
|
3
|
+
## Codegen
|
|
4
|
+
|
|
5
|
+
O servidor **não gera tipos** a partir do schema: a fonte da verdade é o SDL em TypeScript. O codegen é do
|
|
6
|
+
**front** (`@graphql-codegen/cli`, preset `near-operation-file`, `typed-document-node`), que lê o schema por
|
|
7
|
+
**introspecção do GraphQL local rodando**:
|
|
8
|
+
|
|
9
|
+
1. no `.env.local` do servidor: `GRAPHQL_INTROSPECTION=true`;
|
|
10
|
+
2. `npm run dev` no servidor;
|
|
11
|
+
3. `npm run codegen` no front (URL do GraphQL local por variável de ambiente do front);
|
|
12
|
+
4. os `*.generated.ts` vão para o commit; o build não gera nada.
|
|
13
|
+
|
|
14
|
+
Introspecção **nunca** ligada por `NODE_ENV` (nem sempre é `prod` em produção). Alternativa sem subir o
|
|
15
|
+
servidor: um script que monta o schema a partir do código (`makeExecutableSchema` com os mesmos typeDefs) e
|
|
16
|
+
imprime `printSchema(schema)` — útil em CI. Detalhes do lado do front: **angular**.
|
|
17
|
+
|
|
18
|
+
Mudou SDL → rode o codegen do front no mesmo trabalho. Campo renomeado/removido quebra o build do front, o
|
|
19
|
+
que é o objetivo.
|
|
20
|
+
|
|
21
|
+
## Testes (vitest)
|
|
22
|
+
|
|
23
|
+
```ts
|
|
24
|
+
// vitest.config.ts
|
|
25
|
+
import { defineConfig } from 'vitest/config';
|
|
26
|
+
export default defineConfig({
|
|
27
|
+
test: {
|
|
28
|
+
globals: true,
|
|
29
|
+
environment: 'node',
|
|
30
|
+
include: ['tests/**/*.test.ts'],
|
|
31
|
+
exclude: ['tests/integration/**', 'node_modules/**'],
|
|
32
|
+
pool: 'forks',
|
|
33
|
+
},
|
|
34
|
+
});
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Integração em config separada (`vitest.integration.config.ts`, `testTimeout` maior).
|
|
38
|
+
|
|
39
|
+
### Unitário: resolver chamado direto
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
import { describe, it, expect, vi } from 'vitest';
|
|
43
|
+
import { resolvers as Q } from '../../src/web/orders/schemas/order/queries.js';
|
|
44
|
+
|
|
45
|
+
const CALLER = { orfeuCredential: { header: 'x-access-token', value: 'tok' } };
|
|
46
|
+
|
|
47
|
+
it('listOrders: repassa o envelope e aplica os padrões de página', async () => {
|
|
48
|
+
const list = vi.fn(async () => ({ status: 200, message: '', data: { items: [], total: 0, offset: 0 } }));
|
|
49
|
+
const r = await (Q.Query.listOrders as any)(null, {}, { App: { Orders: { list } }, ...CALLER });
|
|
50
|
+
expect(r.status).toBe(200);
|
|
51
|
+
expect(list).toHaveBeenCalledWith(undefined, 0, 50, expect.objectContaining(CALLER));
|
|
52
|
+
});
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
`operation()` devolve o próprio resolver (só marca a função), então dá para chamá-lo sem Orfeu. Teste também
|
|
56
|
+
o `resolve` de subscriptions que remodelam payload e o `failure`/`forward` (`isAxiosError` sem `response` →
|
|
57
|
+
503; `response.data.message` e `detail` em lista → mensagem).
|
|
58
|
+
|
|
59
|
+
### Integração: headers repassados ao serviço de trás
|
|
60
|
+
|
|
61
|
+
Monte um `ApolloServer` real com `orfeuPlugin` e um servidor HTTP local no lugar do serviço, que só registra
|
|
62
|
+
os headers; confira `traceparent`, credencial, `x-route-id`/`x-client-id`:
|
|
63
|
+
|
|
64
|
+
```ts
|
|
65
|
+
const apollo = new ApolloServer({ typeDefs, resolvers, plugins: [orfeuPlugin({} as OrfeuClient)] });
|
|
66
|
+
await apollo.start();
|
|
67
|
+
const res = await apollo.executeOperation(
|
|
68
|
+
{ query: '{ ping }', http: { method: 'POST', headers: new HeaderMap(Object.entries(headers)), search: '', body: {} } },
|
|
69
|
+
{ contextValue: { App: { Orders: orders } } },
|
|
70
|
+
);
|
|
71
|
+
expect(received[0].traceparent).toBe(`00-${TRACE_ID}-${seenTrace.spanId}-01`);
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
(O plugin não chama o Argos; a validação é por campo, no `secureResolvers`, que aqui não é usado.)
|
|
75
|
+
|
|
76
|
+
### O que testar sempre
|
|
77
|
+
|
|
78
|
+
- `assertSchemaSecured` passa com o schema montado (teste que importa o `ExtendedSchema`, monta com um
|
|
79
|
+
`OrfeuClient` falso e chama `secureResolvers` + `makeExecutableSchema` + `assertSchemaSecured`).
|
|
80
|
+
- Funções puras de remodelagem/filtro de payload.
|
|
81
|
+
|
|
82
|
+
Validação focada: rode os testes do que mudou e `npm run typecheck`.
|
|
83
|
+
|
|
84
|
+
## Build
|
|
85
|
+
|
|
86
|
+
Padrão: **`typecheck` + bundle com esbuild** no mesmo script de build. O esbuild gera um arquivo só em
|
|
87
|
+
milissegundos (build de imagem mais rápido, subida sem resolver centenas de módulos) mas **não** checa tipos —
|
|
88
|
+
por isso o `build` roda o `tsc --noEmit` antes, e um erro de tipo nunca chega à imagem. Código que lê arquivo
|
|
89
|
+
relativo ao `dist/` em runtime (`readFileSync`, `__dirname`) quebra no bundle: confira antes de migrar.
|
|
90
|
+
|
|
91
|
+
```json
|
|
92
|
+
{
|
|
93
|
+
"type": "module",
|
|
94
|
+
"scripts": {
|
|
95
|
+
"dev": "cross-env NODE_ENV=local tsx watch src/index.ts",
|
|
96
|
+
"start": "cross-env NODE_ENV=local tsx src/index.ts",
|
|
97
|
+
"start:local": "cross-env NODE_ENV=local tsx watch src/index.ts",
|
|
98
|
+
"start:homol": "cross-env NODE_ENV=homol tsx watch src/index.ts",
|
|
99
|
+
"build": "npm run typecheck && esbuild src/index.ts --bundle --platform=node --format=esm --packages=external --target=es2022 --tsconfig=tsconfig.json --sourcemap --outfile=dist/index.js",
|
|
100
|
+
"typecheck": "tsc --noEmit",
|
|
101
|
+
"start:prod": "node dist/index.js",
|
|
102
|
+
"test": "vitest run"
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
`tsconfig`: `target ES2022`, `module NodeNext`, `strict`, `esModuleInterop`, `skipLibCheck`, `outDir dist`,
|
|
108
|
+
`rootDir src`. Imports relativos com `.js` (o esbuild também resolveria alias `src/*`, mas relativo funciona
|
|
109
|
+
igual no `tsx`, no `vitest` e no `tsc`). Dependências com faixa explícita da versão em uso (`^16.14.2`, não
|
|
110
|
+
`^16`); `@types/node` na major do Node da imagem (`node:22` → `^22`).
|
|
111
|
+
|
|
112
|
+
## Migração Apollo Server 4 → 5
|
|
113
|
+
|
|
114
|
+
- `@apollo/server` `^5` + `@as-integrations/express4` (Express 4) ou `@as-integrations/express5`.
|
|
115
|
+
- `import { expressMiddleware } from '@apollo/server/express4'` → `from '@as-integrations/express4'`.
|
|
116
|
+
- Node ≥ 20. Plugins (`drainHttpServer`) e `executeOperation` não mudam no uso deste padrão.
|
|
117
|
+
- `graphql-ws` 6 muda o import para `graphql-ws/use/ws` e exige Node ≥ 20; o cliente do front fala os dois.
|
|
118
|
+
|
|
119
|
+
## Docker (multi-stage)
|
|
120
|
+
|
|
121
|
+
```dockerfile
|
|
122
|
+
FROM node:22-alpine AS build
|
|
123
|
+
WORKDIR /app
|
|
124
|
+
COPY package.json package-lock.json ./
|
|
125
|
+
RUN --mount=type=cache,target=/root/.npm,sharing=locked \
|
|
126
|
+
timeout -k 10 600 npm ci --no-audit --no-fund
|
|
127
|
+
COPY tsconfig.json ./
|
|
128
|
+
COPY src ./src
|
|
129
|
+
RUN timeout -k 10 300 npm run build \
|
|
130
|
+
&& npm prune --omit=dev --no-audit --no-fund \
|
|
131
|
+
&& find node_modules -type f \( -name '*.d.ts' -o -name '*.d.mts' -o -name '*.d.cts' -o -name '*.map' \
|
|
132
|
+
-o -name '*.md' -o -name '*.markdown' -o -name '*.tsbuildinfo' \) ! -iname 'LICENSE*' -delete \
|
|
133
|
+
&& rm -rf node_modules/@types
|
|
134
|
+
|
|
135
|
+
FROM node:22-alpine
|
|
136
|
+
RUN rm -rf /usr/local/lib/node_modules/npm /usr/local/lib/node_modules/corepack \
|
|
137
|
+
/usr/local/bin/npm /usr/local/bin/npx /usr/local/bin/corepack \
|
|
138
|
+
/opt/yarn-* /usr/local/bin/yarn /usr/local/bin/yarnpkg
|
|
139
|
+
WORKDIR /app
|
|
140
|
+
COPY --from=build /app/package.json ./
|
|
141
|
+
COPY --from=build /app/node_modules ./node_modules
|
|
142
|
+
COPY --from=build /app/dist ./dist
|
|
143
|
+
ENV PORT=3000
|
|
144
|
+
EXPOSE 3000
|
|
145
|
+
CMD ["node", "dist/index.js"]
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
- `CMD` na forma exec com `node` direto (PID 1): `npm start` não repassa `SIGTERM`. O app trata o sinal
|
|
149
|
+
(ver [estrutura-bootstrap.md](estrutura-bootstrap.md)).
|
|
150
|
+
- `timeout` em cada passo que baixa/compila: alguns orquestradores só cancelam o build no passo seguinte.
|
|
151
|
+
- Limpeza do `node_modules` por **tipo de arquivo**, nunca por nome de pasta (pacotes têm código em `docs/`).
|
|
152
|
+
- `.dockerignore`: `.git`, `node_modules`, `dist`, `coverage`, `*.log`, `.env`, `.env.*`, `!.env.example`.
|
|
153
|
+
- A variável de porta do Dockerfile tem de ser a mesma que o código lê.
|
|
154
|
+
|
|
155
|
+
## Variáveis de ambiente (nomes)
|
|
156
|
+
|
|
157
|
+
| Variável | Uso |
|
|
158
|
+
| --- | --- |
|
|
159
|
+
| `NODE_ENV` | escolhe `src/settings/environment/.env.<NODE_ENV>` em dev (`local`, `dev`, `homol`, `prod`) |
|
|
160
|
+
| `PORT` | porta HTTP/WS |
|
|
161
|
+
| `GRAPHQL_PATH` | path do GraphQL **e** do WS (`/graphql`, ou `/<app>/graphql` atrás de proxy) |
|
|
162
|
+
| `AUTHORIZER_URL`, `REALM_ID`, `APP_ID`, `APP_SECRET` | `OrfeuClient` (app registrado no Argos) |
|
|
163
|
+
| `AUTH_TLS_VERIFY` | `false` só se a CA do Argos não está no bundle do Node (prefira `NODE_EXTRA_CA_CERTS`); loga aviso e aparece no `/health` |
|
|
164
|
+
| `PLATFORM_SERVICE_URL` (ou `<SERVICO>_URL`) | `baseURL` dos módulos REST |
|
|
165
|
+
| `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `REDIS_DB`, `REDIS_CHANNEL_PREFIX` | pub/sub; `REDIS_DB` próprio do app (nunca o mesmo de outro app no mesmo Redis), igual ao do server do app |
|
|
166
|
+
| `REDIS_CLUSTER`, `REDIS_HOSTS` | modo cluster |
|
|
167
|
+
| `GRAPHQL_INTROSPECTION` | `true` só onde se roda o codegen |
|
|
168
|
+
|
|
169
|
+
`.env.*` fora do git (`.gitignore`), com `.env.example` só com nomes. Variáveis que o gateway não usa (banco,
|
|
170
|
+
integrações externas) não ficam no `.env` dele.
|
|
171
|
+
|
|
172
|
+
## Logs
|
|
173
|
+
|
|
174
|
+
- Uma linha por operação vem do **logger do Orfeu** (JSON no stdout) e a auditoria vai ao Argos — não
|
|
175
|
+
duplique log por resolver.
|
|
176
|
+
- `console.error` só em erro inesperado (`failure` sem `response`) e falhas de infraestrutura (Redis com log
|
|
177
|
+
limitado a 1x/30s).
|
|
178
|
+
- Nunca logue token, `connectionParams` ou corpo de requisição.
|
|
179
|
+
- Medição de desempenho opcional por variável (`GQL_PERF=1`, limite de lentidão em ms): plugin do Apollo
|
|
180
|
+
(`requestDidStart` → `didResolveOperation`/`willSendResponse`) separando parse/validação de execução, e
|
|
181
|
+
middleware Express antes do `compression()` para o tempo total e bytes enviados.
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Verificador da skill `apollo`: armadilhas de gateways Apollo Server.
|
|
3
|
+
// node checar.mjs [caminhos...] [--json] (instalado: ~/.claude/skills/apollo/scripts/checar.mjs)
|
|
4
|
+
// Exceção: `// acropole-ignore-next-line <regra> -- motivo` na linha anterior.
|
|
5
|
+
// (Campo sem `operation()` já impede a subida pelo `assertSchemaSecured`; não precisa de regra aqui.)
|
|
6
|
+
import fs from 'node:fs';
|
|
7
|
+
import path from 'node:path';
|
|
8
|
+
import { executar } from './nucleo.mjs';
|
|
9
|
+
|
|
10
|
+
const JS = ['.ts', '.js', '.mjs', '.cjs', '.mts', '.cts'];
|
|
11
|
+
const ehCodigo = (a) => JS.includes(a.ext) && !/\.(spec|test)\.[cm]?[jt]s$/.test(a.nome);
|
|
12
|
+
|
|
13
|
+
/** O package.json mais próximo depende de @apollo/server? (cache por pasta) */
|
|
14
|
+
const cache = new Map();
|
|
15
|
+
function projetoApollo(arquivo) {
|
|
16
|
+
let dir = path.dirname(arquivo);
|
|
17
|
+
for (;;) {
|
|
18
|
+
if (cache.has(dir)) return cache.get(dir);
|
|
19
|
+
const pj = path.join(dir, 'package.json');
|
|
20
|
+
if (fs.existsSync(pj)) {
|
|
21
|
+
let sim = false;
|
|
22
|
+
try {
|
|
23
|
+
sim = Boolean(JSON.parse(fs.readFileSync(pj, 'utf8')).dependencies?.['@apollo/server']);
|
|
24
|
+
} catch {
|
|
25
|
+
/* package.json inválido */
|
|
26
|
+
}
|
|
27
|
+
cache.set(dir, sim);
|
|
28
|
+
return sim;
|
|
29
|
+
}
|
|
30
|
+
const pai = path.dirname(dir);
|
|
31
|
+
if (pai === dir) return false;
|
|
32
|
+
dir = pai;
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
// Código do servidor Apollo: fora de testes, scripts e benchmarks.
|
|
36
|
+
const ehServidor = (a) => ehCodigo(a) && !/(^|\/)(tests?|__tests__|scripts|bench\w*)\//.test(a.relRaiz) && projetoApollo(a.caminho);
|
|
37
|
+
|
|
38
|
+
/** Índice do `)`/`]`/`}` que fecha o `(`/`[`/`{` em `inicio`, ignorando strings (texto já sem comentários). */
|
|
39
|
+
function fecha(t, inicio) {
|
|
40
|
+
const par = { '(': ')', '[': ']', '{': '}' };
|
|
41
|
+
const pilha = [];
|
|
42
|
+
let aspas = '';
|
|
43
|
+
for (let i = inicio; i < t.length; i++) {
|
|
44
|
+
const ch = t[i];
|
|
45
|
+
if (aspas) {
|
|
46
|
+
if (ch === '\\') i++;
|
|
47
|
+
else if (ch === aspas) aspas = '';
|
|
48
|
+
} else if (ch === '"' || ch === "'" || ch === '`') aspas = ch;
|
|
49
|
+
else if (par[ch]) pilha.push(par[ch]);
|
|
50
|
+
else if (ch === ')' || ch === ']' || ch === '}') {
|
|
51
|
+
if (pilha.pop() !== ch || !pilha.length) return i; // fechou (ou desbalanceou): para aqui
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
return t.length - 1;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
// Função, método ou constante com nome de contexto de WS: wsContext, buildWsContext, contextForWs, forConnection...
|
|
58
|
+
const NOME_CONTEXTO_WS =
|
|
59
|
+
/^[ \t]*(?:export[ \t]+)?(?:(?:public|private|protected|static|readonly)[ \t]+)*(?:async[ \t]+)?(?:function[ \t]*\*?[ \t]*|(?:const|let|var)[ \t]+)?(\w*(?:ws\w*context|context\w*ws|forconnection)\w*)[ \t]*[=(:<]/gim;
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* Trechos que montam o contexto do WebSocket: os argumentos de `orfeuWsContext(...)`/`useServer(...)` e o corpo
|
|
63
|
+
* de função/método/constante com nome de contexto de WS. Devolve `[inicio, fim]`.
|
|
64
|
+
*/
|
|
65
|
+
function trechosDeContextoWs(t) {
|
|
66
|
+
const out = [];
|
|
67
|
+
for (const m of t.matchAll(/\b(?:orfeuWsContext|useServer)\s*\(/g)) {
|
|
68
|
+
const abre = m.index + m[0].length - 1;
|
|
69
|
+
out.push([abre, fecha(t, abre)]);
|
|
70
|
+
}
|
|
71
|
+
for (const m of t.matchAll(NOME_CONTEXTO_WS)) {
|
|
72
|
+
const abre = t.indexOf('(', m.index + m[0].length - 1);
|
|
73
|
+
if (abre < 0) continue;
|
|
74
|
+
const fimParams = fecha(t, abre);
|
|
75
|
+
// Depois dos parâmetros só pode vir tipo de retorno e então `{` (corpo) ou `=>`; senão é chamada/outra
|
|
76
|
+
// coisa e vale só o que está entre os parênteses.
|
|
77
|
+
const resto = t.slice(fimParams + 1);
|
|
78
|
+
const corpo = resto.search(/=>|\{/);
|
|
79
|
+
if (corpo < 0 || !/^\s*(?::[^;]*?)?\s*$/.test(resto.slice(0, corpo))) {
|
|
80
|
+
out.push([abre, fimParams]);
|
|
81
|
+
continue;
|
|
82
|
+
}
|
|
83
|
+
let j = fimParams + 1 + corpo;
|
|
84
|
+
if (t.startsWith('=>', j)) {
|
|
85
|
+
j += 2;
|
|
86
|
+
while (/\s/.test(t[j] ?? '')) j++;
|
|
87
|
+
if (t[j] === '(' || t[j] === '{') out.push([m.index, fecha(t, j)]);
|
|
88
|
+
else {
|
|
89
|
+
const fimLinha = t.indexOf('\n', j);
|
|
90
|
+
out.push([m.index, fimLinha < 0 ? t.length - 1 : fimLinha]);
|
|
91
|
+
}
|
|
92
|
+
} else out.push([m.index, fecha(t, j)]);
|
|
93
|
+
}
|
|
94
|
+
return out;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
const regras = [
|
|
98
|
+
{
|
|
99
|
+
id: 'apollo-express4-legado',
|
|
100
|
+
resumo: "import de '@apollo/server/express4' (Apollo Server 4, fora de suporte)",
|
|
101
|
+
aceita: ehCodigo,
|
|
102
|
+
checar: (arq) =>
|
|
103
|
+
[...arq.limpo.matchAll(/['"]@apollo\/server\/express4['"]/g)].map((m) => ({
|
|
104
|
+
linha: arq.linhaDe(m.index),
|
|
105
|
+
mensagem: '`@apollo/server/express4` é do Apollo Server 4, fora de suporte',
|
|
106
|
+
correcao: 'migre para `@apollo/server` 5 + `@as-integrations/express5` (ou `express4`) — references/testes-build.md',
|
|
107
|
+
})),
|
|
108
|
+
},
|
|
109
|
+
{
|
|
110
|
+
id: 'env-no-topo',
|
|
111
|
+
resumo: 'process.env lido em constante de topo de módulo (ESM roda antes do dotenv)',
|
|
112
|
+
aceita: (a) => ehServidor(a) && !/\bdotenv\b/.test(a.limpo),
|
|
113
|
+
checar(arq) {
|
|
114
|
+
const out = [];
|
|
115
|
+
for (const m of arq.limpo.matchAll(/^(?:export[ \t]+)?(?:const|let|var)[ \t]+[^\n=]+=([^\n]*)$/gm)) {
|
|
116
|
+
const resto = m[1];
|
|
117
|
+
const env = resto.search(/\bprocess\.env\b/);
|
|
118
|
+
if (env < 0 || /=>|\bfunction\b/.test(resto.slice(0, env))) continue;
|
|
119
|
+
if (/^\s*process\.env\.NODE_ENV\b/.test(resto.slice(env))) continue;
|
|
120
|
+
out.push({
|
|
121
|
+
linha: arq.linhaDe(m.index),
|
|
122
|
+
mensagem: '`process.env` lido no topo do módulo: em ESM os imports rodam antes do `dotenv.config()` e o valor sai vazio (Redis cai em localhost em silêncio)',
|
|
123
|
+
correcao: 'leia dentro do builder ou de forma preguiçosa (função `getX()` chamada depois da configuração)',
|
|
124
|
+
});
|
|
125
|
+
}
|
|
126
|
+
return out;
|
|
127
|
+
},
|
|
128
|
+
},
|
|
129
|
+
{
|
|
130
|
+
id: 'ws-connection-params-espalhado',
|
|
131
|
+
resumo: '...connectionParams no contexto do WebSocket (orfeuWsContext/useServer ou função de contexto de WS)',
|
|
132
|
+
aceita: ehServidor,
|
|
133
|
+
checar(arq) {
|
|
134
|
+
const t = arq.limpo;
|
|
135
|
+
const vistos = new Set();
|
|
136
|
+
const out = [];
|
|
137
|
+
for (const [ini, fim] of trechosDeContextoWs(t)) {
|
|
138
|
+
// `...connectionParams`, `...ctx.connectionParams`, `...(ctx?.connectionParams ?? {})`, `...connectionParams.headers`
|
|
139
|
+
for (const m of t.slice(ini, fim + 1).matchAll(/\.\.\.\s*\(?\s*(?:[\w$]+\s*\??\.\s*)*connectionParams\b/g)) {
|
|
140
|
+
const idx = ini + m.index;
|
|
141
|
+
if (vistos.has(idx)) continue;
|
|
142
|
+
vistos.add(idx);
|
|
143
|
+
out.push({
|
|
144
|
+
linha: arq.linhaDe(idx),
|
|
145
|
+
mensagem: '`connectionParams` espalhado no contexto do WebSocket: o cliente escreve no `connection_init` qualquer chave, que chega ao `ctx` dos resolvers (com `@orfeu/node` 1.0.0, até o `orfeuUser`)',
|
|
146
|
+
correcao: 'repasse só a allowlist `x-access-token`, `x-app-token`, `x-api-token`, `traceparent`, `x-route-id`, `x-client-id`, com valor string (`wsContextParams`, references/subscriptions.md), e exija `@orfeu/node` ^1.0.1',
|
|
147
|
+
});
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
return out;
|
|
151
|
+
},
|
|
152
|
+
},
|
|
153
|
+
];
|
|
154
|
+
|
|
155
|
+
process.exitCode = executar({
|
|
156
|
+
skill: 'apollo',
|
|
157
|
+
descricao: 'Apollo Server 4 legado, process.env lido no topo do módulo e connectionParams espalhado no contexto do WebSocket.',
|
|
158
|
+
regras,
|
|
159
|
+
extensoes: JS,
|
|
160
|
+
});
|