@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,310 @@
|
|
|
1
|
+
# Estrutura e bootstrap
|
|
2
|
+
|
|
3
|
+
O servidor é **Apollo Server montado no Express** (`expressMiddleware`), não o modo standalone: o mesmo
|
|
4
|
+
`http.Server` serve o GraphQL (HTTP), o WebSocket das subscriptions e, quando preciso, rotas REST auxiliares
|
|
5
|
+
(upload, proxy de arquivo). Express em si: **express**.
|
|
6
|
+
|
|
7
|
+
## `src/index.ts`
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
console.time('Server | Load Time');
|
|
11
|
+
|
|
12
|
+
import * as dotenv from 'dotenv';
|
|
13
|
+
dotenv.config({ path: `src/settings/environment/.env.${process.env.NODE_ENV ?? 'local'}` });
|
|
14
|
+
|
|
15
|
+
import builder from './core/builder.js';
|
|
16
|
+
|
|
17
|
+
try {
|
|
18
|
+
await builder(process.env);
|
|
19
|
+
} catch (error) {
|
|
20
|
+
console.error('Falha na subida:', error);
|
|
21
|
+
process.exit(1); // sem isto o processo fica de pé sem servir nada
|
|
22
|
+
}
|
|
23
|
+
console.timeEnd('Server | Load Time');
|
|
24
|
+
|
|
25
|
+
process.on('unhandledRejection', (reason) => console.error('unhandledRejection:', reason));
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
- `NODE_ENV` com padrão (`?? 'local'`): sem ele o dotenv procura `.env.undefined`.
|
|
29
|
+
- No container o `.env.*` não é copiado (só `dist/`): as variáveis vêm do ambiente do container e o
|
|
30
|
+
`dotenv.config` simplesmente não acha o arquivo — é o esperado.
|
|
31
|
+
- **Atenção ao ESM**: o `import builder` é avaliado ANTES do `dotenv.config()` (imports estáticos sobem
|
|
32
|
+
primeiro). Nada no grafo de imports pode ler `process.env` em escopo de módulo — leia dentro de funções.
|
|
33
|
+
|
|
34
|
+
## `src/core/builder.ts` (padrão)
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
import compression from 'compression';
|
|
38
|
+
import express from 'express';
|
|
39
|
+
import cors from 'cors';
|
|
40
|
+
import { makeExecutableSchema } from '@graphql-tools/schema';
|
|
41
|
+
import { expressMiddleware } from '@as-integrations/express4';
|
|
42
|
+
import { OrfeuClient, OrfeuConfigError } from '@orfeu/node';
|
|
43
|
+
import { assertSchemaSecured, orfeuWsContext, secureResolvers } from '@orfeu/node/apollo';
|
|
44
|
+
|
|
45
|
+
import { BASE_SCHEMA } from './schema/index.js';
|
|
46
|
+
import { HttpServer } from './server/http.server.js';
|
|
47
|
+
import { WsServer } from './server/ws.server.js';
|
|
48
|
+
import { ApolloServer } from './server/apollo.server.js';
|
|
49
|
+
import { wsContextParams } from './context/ws-context.js';
|
|
50
|
+
import { AppModules } from '../web/config/index.js';
|
|
51
|
+
import { ExtendedSchema } from '../web/config/schemas/schemas.extends.js';
|
|
52
|
+
import type { GraphQLContext } from './context/context.types.js';
|
|
53
|
+
|
|
54
|
+
export default async (settings: NodeJS.ProcessEnv) => {
|
|
55
|
+
const tlsVerify = settings.AUTH_TLS_VERIFY !== 'false'; // opt-out; prefira NODE_EXTRA_CA_CERTS com a CA do ambiente
|
|
56
|
+
const orfeu = new OrfeuClient({
|
|
57
|
+
authorizerUrl: settings.AUTHORIZER_URL!,
|
|
58
|
+
realmId: settings.REALM_ID!,
|
|
59
|
+
appId: settings.APP_ID!,
|
|
60
|
+
secret: settings.APP_SECRET!,
|
|
61
|
+
tlsVerify,
|
|
62
|
+
});
|
|
63
|
+
if (!tlsVerify) console.warn('AUTH_TLS_VERIFY=false: o certificado do Argos NÃO é verificado (inclusive o JWKS).');
|
|
64
|
+
|
|
65
|
+
// 1) schema seguro ANTES do startup (o startup sincroniza as operações registradas com o Argos)
|
|
66
|
+
const extended = new ExtendedSchema();
|
|
67
|
+
const resolvers = secureResolvers(orfeu, extended.resolvers, {
|
|
68
|
+
onForbidden: () => ({ status: 403, message: 'Você não tem permissão para esta operação.', data: null }),
|
|
69
|
+
});
|
|
70
|
+
const schema = makeExecutableSchema({ typeDefs: [...BASE_SCHEMA, ...extended.typeDefs], resolvers });
|
|
71
|
+
assertSchemaSecured(schema);
|
|
72
|
+
|
|
73
|
+
// 2) Orfeu: sobe e NEGA tudo até conectar, com nova tentativa de espera crescente (5 s → 30 s).
|
|
74
|
+
// Erro de configuração (OrfeuConfigError) não melhora tentando de novo: derruba a subida.
|
|
75
|
+
const status = { orfeuReady: false };
|
|
76
|
+
const startOrfeu = async (attempt = 1): Promise<void> => {
|
|
77
|
+
try {
|
|
78
|
+
await orfeu.startup();
|
|
79
|
+
status.orfeuReady = true;
|
|
80
|
+
} catch (err: any) {
|
|
81
|
+
if (err instanceof OrfeuConfigError) throw err;
|
|
82
|
+
const delay = Math.min(5_000 * 2 ** (attempt - 1), 30_000);
|
|
83
|
+
console.warn(`Orfeu indisponível (tentativa ${attempt}); operações negadas; nova tentativa em ${delay / 1000}s`);
|
|
84
|
+
setTimeout(() => void startOrfeu(attempt + 1), delay).unref();
|
|
85
|
+
}
|
|
86
|
+
};
|
|
87
|
+
await startOrfeu();
|
|
88
|
+
|
|
89
|
+
// 3) módulos (clientes REST) — criados aqui, depois do dotenv
|
|
90
|
+
const appMods = await AppModules.start(settings);
|
|
91
|
+
|
|
92
|
+
// 4) servidores: o MESMO path no HTTP e no WS
|
|
93
|
+
const graphqlPath = settings.GRAPHQL_PATH ?? '/graphql';
|
|
94
|
+
const app = express();
|
|
95
|
+
const http = new HttpServer(app);
|
|
96
|
+
// extra do WS: módulos + só a allowlist do connectionParams (nunca `...connectionParams`)
|
|
97
|
+
const ws = new WsServer(http.server, schema,
|
|
98
|
+
orfeuWsContext(orfeu, (ctx) => ({ App: appMods, ...wsContextParams(ctx) })), graphqlPath);
|
|
99
|
+
const apollo = new ApolloServer(schema, http.server, ws.serverCleanup, orfeu);
|
|
100
|
+
await apollo.server.start();
|
|
101
|
+
|
|
102
|
+
// probe sem auth (rota Express, fora do Orfeu): 503 enquanto o Orfeu não conecta, 200 depois
|
|
103
|
+
app.get('/health', (_req, res) => {
|
|
104
|
+
const tls = tlsVerify ? {} : { tls_verify: false };
|
|
105
|
+
if (!status.orfeuReady) { res.status(503).json({ status: 'starting', orfeu: 'unavailable', ...tls }); return; }
|
|
106
|
+
res.status(200).json({ ok: true, ...tls });
|
|
107
|
+
});
|
|
108
|
+
app.use(
|
|
109
|
+
graphqlPath,
|
|
110
|
+
compression(), // JSON comprime 70–85%: padrão, não otimização opcional
|
|
111
|
+
cors<cors.CorsRequest>(),
|
|
112
|
+
express.json({ limit: '2mb' }),
|
|
113
|
+
expressMiddleware(apollo.server, {
|
|
114
|
+
context: async ({ req }): Promise<GraphQLContext> => ({ App: appMods, req }),
|
|
115
|
+
}),
|
|
116
|
+
);
|
|
117
|
+
|
|
118
|
+
const port = Number(settings.PORT ?? 3000);
|
|
119
|
+
http.server.listen(port, () => console.log(`GraphQL → http://localhost:${port}${graphqlPath}`));
|
|
120
|
+
|
|
121
|
+
// 5) encerramento: node é PID 1 no container; sem handler o stop espera o SIGKILL.
|
|
122
|
+
// Encerramento completo sai com 0; estourar o teto de 8 s sai com 1 (o orquestrador distingue).
|
|
123
|
+
for (const signal of ['SIGTERM', 'SIGINT'] as const) {
|
|
124
|
+
process.once(signal, async () => {
|
|
125
|
+
setTimeout(() => process.exit(1), 8_000).unref();
|
|
126
|
+
await orfeu.close().catch(() => undefined); // para a recarga de permissões + envia a fila de auditoria (SDK antigo: flushAudit())
|
|
127
|
+
await apollo.server.stop().catch(() => undefined); // drain: fecha HTTP e WS
|
|
128
|
+
process.exit(0);
|
|
129
|
+
});
|
|
130
|
+
}
|
|
131
|
+
};
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Pontos:
|
|
135
|
+
|
|
136
|
+
- O contexto HTTP só precisa de `{ App, req }`: os campos `orfeu*` (credencial, trace, routeId/clientId) são
|
|
137
|
+
preenchidos pelo `orfeuPlugin` no `didResolveOperation`. Não valide token no `context` — a validação é
|
|
138
|
+
por campo, no `secureResolvers`.
|
|
139
|
+
- `@orfeu/node` `^1.0.1` no `package.json` (a 1.0.0 aceitava `orfeuUser` forjado pelo `connectionParams`).
|
|
140
|
+
O contexto do WS (`ws-context.ts`, com a allowlist) está em [subscriptions.md](subscriptions.md).
|
|
141
|
+
|
|
142
|
+
### Orfeu fora do ar na subida: sobe negando (padrão)
|
|
143
|
+
|
|
144
|
+
Padrão único dos gateways — **nunca** um "modo degradado" que libera tudo, e também não cair em loop:
|
|
145
|
+
|
|
146
|
+
- O servidor **sobe** e o `/health` responde **503** (`{ status: 'starting', orfeu: 'unavailable' }`) até o
|
|
147
|
+
`startup()` completar; toda operação não pública é negada (401 sem token, 401/403 com token — sem JWKS e sem
|
|
148
|
+
catálogo sincronizado) e nenhuma chega ao backend.
|
|
149
|
+
- Nova tentativa com espera crescente: 5 s, 10 s, 20 s, depois a cada 30 s. Volta sozinho quando o Argos volta,
|
|
150
|
+
sem loop de restart do container.
|
|
151
|
+
- `OrfeuConfigError` (ex.: nenhuma operação registrada) **derruba** a subida: o `index.ts` sai com 1.
|
|
152
|
+
- O 503 não deve reiniciar o container: se o orquestrador tiver healthcheck ativo, ele precisa tolerar a subida.
|
|
153
|
+
- Teste obrigatório (`tests/integration/builder-falha.test.ts`): com o Orfeu fora, o servidor escuta, `/health`
|
|
154
|
+
dá 503, toda operação é negada sem chegar ao backend, e após a nova tentativa `/health` passa a 200.
|
|
155
|
+
|
|
156
|
+
O `secureResolvers` e o `assertSchemaSecured` continuam **antes** de qualquer tentativa (o catálogo precisa
|
|
157
|
+
estar registrado quando o `startup()` sincronizar).
|
|
158
|
+
|
|
159
|
+
- `compression()` antes do Apollo em todo gateway (JSON comprime 70–85%; respostas de vários MB caem para centenas de KB).
|
|
160
|
+
|
|
161
|
+
## `src/core/server/*.ts`
|
|
162
|
+
|
|
163
|
+
```ts
|
|
164
|
+
// http.server.ts
|
|
165
|
+
import http from 'node:http';
|
|
166
|
+
import type { Express } from 'express';
|
|
167
|
+
export class HttpServer {
|
|
168
|
+
public server: http.Server;
|
|
169
|
+
constructor(app: Express) { this.server = http.createServer(app); }
|
|
170
|
+
}
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
```ts
|
|
174
|
+
// ws.server.ts (graphql-ws 5: 'graphql-ws/lib/use/ws'; graphql-ws 6: 'graphql-ws/use/ws')
|
|
175
|
+
import { WebSocketServer } from 'ws';
|
|
176
|
+
import { useServer } from 'graphql-ws/lib/use/ws';
|
|
177
|
+
import type { GraphQLSchema } from 'graphql';
|
|
178
|
+
import type http from 'node:http';
|
|
179
|
+
|
|
180
|
+
export class WsServer {
|
|
181
|
+
public server: WebSocketServer;
|
|
182
|
+
public serverCleanup: ReturnType<typeof useServer>;
|
|
183
|
+
constructor(httpServer: http.Server, schema: GraphQLSchema, context: (ctx: any) => Promise<unknown>, path: string) {
|
|
184
|
+
this.server = new WebSocketServer({ server: httpServer, path });
|
|
185
|
+
// `as any`: sob NodeNext o @types/ws pode resolver duas vezes (import/require) e o TS vê dois tipos distintos
|
|
186
|
+
this.serverCleanup = useServer({ schema, context }, this.server as any);
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
```ts
|
|
192
|
+
// apollo.server.ts (Apollo Server 5)
|
|
193
|
+
import { ApolloServer as ApolloBase } from '@apollo/server';
|
|
194
|
+
import { ApolloServerPluginDrainHttpServer } from '@apollo/server/plugin/drainHttpServer';
|
|
195
|
+
import { orfeuPlugin } from '@orfeu/node/apollo';
|
|
196
|
+
import type { OrfeuClient } from '@orfeu/node';
|
|
197
|
+
import type { GraphQLSchema } from 'graphql';
|
|
198
|
+
import type http from 'node:http';
|
|
199
|
+
import type { GraphQLContext } from '../context/context.types.js';
|
|
200
|
+
|
|
201
|
+
export class ApolloServer {
|
|
202
|
+
public server: ApolloBase<GraphQLContext>;
|
|
203
|
+
constructor(schema: GraphQLSchema, httpServer: http.Server,
|
|
204
|
+
wsCleanup: { dispose: () => void | Promise<void> }, orfeu: OrfeuClient) {
|
|
205
|
+
this.server = new ApolloBase<GraphQLContext>({
|
|
206
|
+
schema,
|
|
207
|
+
allowBatchedHttpRequests: true, // o front usa HttpBatchLink
|
|
208
|
+
introspection: process.env.GRAPHQL_INTROSPECTION === 'true', // só para o codegen local
|
|
209
|
+
plugins: [
|
|
210
|
+
ApolloServerPluginDrainHttpServer({ httpServer }),
|
|
211
|
+
orfeuPlugin(orfeu),
|
|
212
|
+
{ async serverWillStart() { return { async drainServer() { await wsCleanup.dispose(); } }; } },
|
|
213
|
+
],
|
|
214
|
+
});
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
## Contexto tipado
|
|
220
|
+
|
|
221
|
+
```ts
|
|
222
|
+
// src/core/context/context.types.ts
|
|
223
|
+
import type { Request } from 'express';
|
|
224
|
+
import type { OrfeuContext } from '@orfeu/node/apollo';
|
|
225
|
+
import type { AppModules } from '../../web/config/index.types.js';
|
|
226
|
+
|
|
227
|
+
export type GraphQLContext = OrfeuContext & { App: AppModules; req?: Request };
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
- No HTTP `req` existe; no WS não (há `connectionParams`). Use `req?` ou um tipo separado para
|
|
231
|
+
subscriptions.
|
|
232
|
+
- O usuário validado fica em `ctx.orfeuUser` **depois** do guard do campo — não leia no `context()`.
|
|
233
|
+
- Evite o padrão antigo de montar `metadata = { token, user }` à mão no contexto validando o token com
|
|
234
|
+
`orfeu.validateToken`: duplica o trabalho do `secureResolvers` e diverge dele. Se o contexto realmente
|
|
235
|
+
precisa de um usuário validado por fora (sem credencial crua), ele entra por `trustUser(ctx, claims)`;
|
|
236
|
+
`ctx.orfeuUser = ...` gravado à mão responde 401 desde o `@orfeu/node` 1.0.1 (skill **orfeu**).
|
|
237
|
+
|
|
238
|
+
## `AppModules` (composição)
|
|
239
|
+
|
|
240
|
+
```ts
|
|
241
|
+
// src/web/config/index.ts
|
|
242
|
+
import { TagsModule } from '../tags/modules/index.js';
|
|
243
|
+
import { OrdersModule } from '../orders/modules/index.js';
|
|
244
|
+
import type { AppModules as IAppModules } from './index.types.js';
|
|
245
|
+
|
|
246
|
+
export class AppModules implements IAppModules {
|
|
247
|
+
constructor(public Tags: TagsModule, public Orders: OrdersModule) {}
|
|
248
|
+
static async start(settings: NodeJS.ProcessEnv): Promise<AppModules> {
|
|
249
|
+
return new AppModules(new TagsModule(settings), new OrdersModule(settings));
|
|
250
|
+
}
|
|
251
|
+
}
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
`index.types.ts` declara só a interface (`Tags: TagsModule; ...`) e existe para quebrar o ciclo de import
|
|
255
|
+
entre `context.types.ts` e os módulos. Um módulo por domínio, nome em PascalCase igual ao do domínio
|
|
256
|
+
(`ctx.App.Orders`).
|
|
257
|
+
|
|
258
|
+
## `ExtendedSchema` (composição do schema)
|
|
259
|
+
|
|
260
|
+
```ts
|
|
261
|
+
// src/web/config/schemas/schemas.extends.ts
|
|
262
|
+
import merge from 'lodash/merge.js';
|
|
263
|
+
import type { IResolvers } from '@graphql-tools/utils';
|
|
264
|
+
import { Level } from '@orfeu/node';
|
|
265
|
+
import { operation } from '@orfeu/node/apollo';
|
|
266
|
+
import { JSONScalar } from '../../../core/schema/scalars.js';
|
|
267
|
+
import { TAGS_SCHEMA, TAGS_RESOLVERS } from '../../tags/schemas/index.js';
|
|
268
|
+
import { ORDERS_SCHEMA, ORDERS_RESOLVERS } from '../../orders/schemas/index.js';
|
|
269
|
+
|
|
270
|
+
export class ExtendedSchema {
|
|
271
|
+
public typeDefs: string[] = [
|
|
272
|
+
`#graphql
|
|
273
|
+
extend type Query { _health: String! }
|
|
274
|
+
`,
|
|
275
|
+
...TAGS_SCHEMA,
|
|
276
|
+
...ORDERS_SCHEMA,
|
|
277
|
+
];
|
|
278
|
+
public resolvers: IResolvers = merge(
|
|
279
|
+
{ JSON: JSONScalar, Query: { _health: operation(Level.PUBLIC, () => 'ok') } },
|
|
280
|
+
TAGS_RESOLVERS,
|
|
281
|
+
ORDERS_RESOLVERS,
|
|
282
|
+
);
|
|
283
|
+
}
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
`BASE_SCHEMA` declara os tipos raiz vazios (`type Query`, `type Mutation`, `type Subscription`) e os
|
|
287
|
+
scalars. Se `Mutation` ou `Subscription` acabar sem nenhum campo, o schema não valida: remova o tipo raiz
|
|
288
|
+
vazio do `BASE_SCHEMA` ou adicione um campo real (evite campos `_noop` só para tapar).
|
|
289
|
+
|
|
290
|
+
## Rotas REST ao lado do GraphQL
|
|
291
|
+
|
|
292
|
+
Upload de arquivo e leitura de binário (imagem) **não** passam pelo Apollo (evita `graphql-upload`). Monte um
|
|
293
|
+
`express.Router()` na base do path (`/app/graphql` → `/app`), faça proxy em stream para o serviço de trás e
|
|
294
|
+
repasse os headers do Orfeu com uma função própria (não há `OrfeuContext` fora do Apollo):
|
|
295
|
+
|
|
296
|
+
```ts
|
|
297
|
+
import type { Request } from 'express';
|
|
298
|
+
import { ACCESS_TOKEN_HEADER, APP_TOKEN_HEADER, CLIENT_ID_HEADER, ROUTE_ID_HEADER, TRACEPARENT_HEADER } from '@orfeu/node';
|
|
299
|
+
|
|
300
|
+
export function passthroughHeaders(req: Request): Record<string, string> {
|
|
301
|
+
const out: Record<string, string> = {};
|
|
302
|
+
const get = (n: string) => { const v = req.headers[n]; return (Array.isArray(v) ? v[0] : v)?.trim() || undefined; };
|
|
303
|
+
for (const n of [ACCESS_TOKEN_HEADER, APP_TOKEN_HEADER]) { const v = get(n); if (v) { out[n] = v; break; } }
|
|
304
|
+
for (const n of [TRACEPARENT_HEADER, ROUTE_ID_HEADER, CLIENT_ID_HEADER]) { const v = get(n); if (v) out[n] = v; }
|
|
305
|
+
return out;
|
|
306
|
+
}
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
O `traceparent` vai sem span novo (o gateway não audita essas rotas). Detalhes de proxy/stream:
|
|
310
|
+
**express**.
|
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
# Schema, resolvers e módulos
|
|
2
|
+
|
|
3
|
+
## SDL-first, em TypeScript
|
|
4
|
+
|
|
5
|
+
- O schema é **SDL** (não code-first), escrito em template strings com o marcador `#graphql` (realce de
|
|
6
|
+
sintaxe e o GraphQL do VS Code reconhecem). Não há `.graphql` no servidor — os `.graphql` com as
|
|
7
|
+
**operações** ficam no front (ver **angular**).
|
|
8
|
+
- `makeExecutableSchema({ typeDefs, resolvers })` de `@graphql-tools/schema` junta tudo.
|
|
9
|
+
- Cada arquivo de recurso exporta `schema: string[]` e `resolvers`. Mantenha o `schema` como **array** (permite
|
|
10
|
+
`...spread` sem caso especial) e use `schema: string[] = []` quando não houver nada — não `[``]`.
|
|
11
|
+
|
|
12
|
+
## Organização por domínio
|
|
13
|
+
|
|
14
|
+
```
|
|
15
|
+
web/orders/
|
|
16
|
+
modules/index.ts OrdersModule (REST)
|
|
17
|
+
schemas/
|
|
18
|
+
order/queries.ts extend type Query { ... } + tipos de leitura + resolvers.Query
|
|
19
|
+
order/mutations.ts extend type Mutation { ... } + inputs + resolvers.Mutation
|
|
20
|
+
order/subscriptions.ts extend type Subscription { ... } + resolvers.Subscription
|
|
21
|
+
order/index.ts reexporta com nomes únicos
|
|
22
|
+
index.ts ORDERS_SCHEMA / ORDERS_RESOLVERS
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
// order/index.ts
|
|
27
|
+
export { schema as ORDER_QUERIES_SCHEMA, resolvers as ORDER_QUERIES_RESOLVERS } from './queries.js';
|
|
28
|
+
export { schema as ORDER_MUTATIONS_SCHEMA, resolvers as ORDER_MUTATIONS_RESOLVERS } from './mutations.js';
|
|
29
|
+
export { schema as ORDER_SUBSCRIPTIONS_SCHEMA, resolvers as ORDER_SUBSCRIPTIONS_RESOLVERS } from './subscriptions.js';
|
|
30
|
+
|
|
31
|
+
// schemas/index.ts
|
|
32
|
+
import merge from 'lodash/merge.js';
|
|
33
|
+
import * as O from './order/index.js';
|
|
34
|
+
export const ORDERS_SCHEMA = [...O.ORDER_QUERIES_SCHEMA, ...O.ORDER_MUTATIONS_SCHEMA, ...O.ORDER_SUBSCRIPTIONS_SCHEMA];
|
|
35
|
+
export const ORDERS_RESOLVERS = merge({}, O.ORDER_QUERIES_RESOLVERS, O.ORDER_MUTATIONS_RESOLVERS, O.ORDER_SUBSCRIPTIONS_RESOLVERS);
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
- `merge` **sempre com `{}` como primeiro argumento** — `merge(a, b)` muta `a`.
|
|
39
|
+
- Importe `lodash/merge.js` (ESM + NodeNext) ou `import pkg from 'lodash'; const { merge } = pkg;`. Não
|
|
40
|
+
`import { merge } from 'lodash'` (CommonJS sem export nomeado em ESM).
|
|
41
|
+
- Tipos compartilhados entre domínios (ex.: `Environment`, tipos de um inventário comum) vão num domínio
|
|
42
|
+
`shared/` que entra primeiro no `ExtendedSchema`. Tipos de outro domínio podem ser estendidos
|
|
43
|
+
(`extend type Pool { ... }`), mas isso cria acoplamento de ordem — prefira tipos próprios.
|
|
44
|
+
|
|
45
|
+
## Convenções de SDL
|
|
46
|
+
|
|
47
|
+
| Item | Convenção |
|
|
48
|
+
| --- | --- |
|
|
49
|
+
| Campo raiz | camelCase, verbo + recurso: `listOrders`, `getOrder`, `createOrder`, `updateOrder`, `deleteOrder`; subscription: `orderChanged` / `subscribeOrderX` |
|
|
50
|
+
| Remoção | começa com `delete`/`remove`/`destroy` (vira método `delete` no Orfeu) |
|
|
51
|
+
| Retorno de Query/Mutation | `<Nome>Response!` (não-nulo), gerado por `envelopeType` |
|
|
52
|
+
| `data` do envelope | **sempre anulável** (`data: Order`, `data: [Order!]`) — falha devolve `data: null` |
|
|
53
|
+
| Inputs | `input CreateOrderInput`, `input UpdateOrderInput` (campos opcionais no update) |
|
|
54
|
+
| Remoção sem retorno | `envelopeType('MutationResult', 'ID')` reaproveitado |
|
|
55
|
+
| Nomes de campo | os mesmos que o serviço de trás devolve (snake_case ou camelCase, o que vier) — o gateway não renomeia |
|
|
56
|
+
| Docs | string de descrição no SDL (`"..."` ou `"""..."""`) nos campos raiz; aparece no codegen |
|
|
57
|
+
|
|
58
|
+
Declare cada `envelopeType(...)` **uma vez** no schema inteiro (tipo duplicado quebra o `makeExecutableSchema`).
|
|
59
|
+
|
|
60
|
+
## Scalars
|
|
61
|
+
|
|
62
|
+
```ts
|
|
63
|
+
// core/schema/scalars.ts
|
|
64
|
+
import { GraphQLScalarType, Kind, type ValueNode } from 'graphql';
|
|
65
|
+
|
|
66
|
+
function parseLiteral(ast: ValueNode): unknown {
|
|
67
|
+
switch (ast.kind) {
|
|
68
|
+
case Kind.STRING: case Kind.BOOLEAN: return ast.value;
|
|
69
|
+
case Kind.INT: case Kind.FLOAT: return Number(ast.value);
|
|
70
|
+
case Kind.OBJECT: return Object.fromEntries(ast.fields.map((f) => [f.name.value, parseLiteral(f.value)]));
|
|
71
|
+
case Kind.LIST: return ast.values.map(parseLiteral);
|
|
72
|
+
default: return null;
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
export const JSONScalar = new GraphQLScalarType({
|
|
77
|
+
name: 'JSON',
|
|
78
|
+
description: 'Valor JSON arbitrário (payloads dinâmicos).',
|
|
79
|
+
serialize: (v) => v, parseValue: (v) => v, parseLiteral,
|
|
80
|
+
});
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
`scalar JSON` no `BASE_SCHEMA` + `JSON: JSONScalar` nos resolvers. Use `JSON` só para payload realmente
|
|
84
|
+
dinâmico — tipo explícito dá codegen útil no front. Datas trafegam como `String` ISO 8601.
|
|
85
|
+
|
|
86
|
+
## Resolvers
|
|
87
|
+
|
|
88
|
+
```ts
|
|
89
|
+
createOrder: operation(Level.PRIVATE, (_: unknown, { input }: { input: CreateOrderInput }, ctx: GraphQLContext) =>
|
|
90
|
+
forward(() => ctx.App.Orders.create(input, ctx))),
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
- Uma linha: `operation(nível, (parent, args, ctx) => forward(() => ctx.App.<Dominio>.<metodo>(..., ctx)))`.
|
|
94
|
+
- O resolver **traduz argumentos** (GraphQL camelCase → query string do serviço, omitindo vazios) e mais
|
|
95
|
+
nada. Sem `try/catch` próprio (o `forward` cuida), sem texto de mensagem, sem transformar `data`.
|
|
96
|
+
- Exceção aceitável: remodelar um payload que o serviço publica num formato que o GraphQL não expressa
|
|
97
|
+
(ex.: dicionário `{ chave: valor }` → lista `[{ key, value }]`), de preferência numa função pura testada.
|
|
98
|
+
- Tipar `args` e `ctx` (`GraphQLContext`). `any` em `ctx` esconde o erro de `ctx.App` ausente no WS.
|
|
99
|
+
- Resolver de campo de tipo (não raiz) não passa pelo Orfeu e não precisa de `operation()`; evite fazer
|
|
100
|
+
chamada remota nele (N+1) — peça o dado já montado ao serviço de trás.
|
|
101
|
+
|
|
102
|
+
## Módulos (clientes dos serviços de trás)
|
|
103
|
+
|
|
104
|
+
```ts
|
|
105
|
+
import axios, { type AxiosInstance } from 'axios';
|
|
106
|
+
import { orfeuHeaders, type OrfeuForwardSource } from '@orfeu/node';
|
|
107
|
+
|
|
108
|
+
export class OrdersModule {
|
|
109
|
+
private http: AxiosInstance;
|
|
110
|
+
constructor(settings: NodeJS.ProcessEnv) {
|
|
111
|
+
this.http = axios.create({ baseURL: settings.PLATFORM_SERVICE_URL, timeout: 30_000 });
|
|
112
|
+
}
|
|
113
|
+
async create(body: unknown, caller: OrfeuForwardSource) {
|
|
114
|
+
const { data } = await this.http.post('/orders', body, { headers: orfeuHeaders(caller) });
|
|
115
|
+
return data; // envelope do serviço
|
|
116
|
+
}
|
|
117
|
+
async remove(orderId: string, caller: OrfeuForwardSource) {
|
|
118
|
+
const { data } = await this.http.delete(`/orders/${encodeURIComponent(orderId)}`, { headers: orfeuHeaders(caller) });
|
|
119
|
+
return data;
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
- `axios.create` **no construtor** (depois do dotenv), `baseURL` de variável de ambiente.
|
|
125
|
+
- Último parâmetro sempre `caller: OrfeuForwardSource` — o próprio `ctx`. `orfeuHeaders(ctx)` envia a
|
|
126
|
+
credencial recebida (`x-access-token` → `x-app-token` → `x-api-token`), o `traceparent` com o span DESTE
|
|
127
|
+
salto e `x-route-id`/`x-client-id`. Sem isso o serviço de trás grava a ação como entrada nova e a auditoria
|
|
128
|
+
aparece partida em dois traces. Detalhes: **orfeu**.
|
|
129
|
+
- `encodeURIComponent` em id que vai no path.
|
|
130
|
+
- Um módulo pode agrupar vários sub-recursos do mesmo prefixo REST (uma classe com seções), desde que siga
|
|
131
|
+
o mesmo serviço de trás.
|
|
132
|
+
- Status de negócio que **não** é erro mas vem como 4xx (ex.: 422 com a lista de achados em `data`): aceite
|
|
133
|
+
com `validateStatus` só naquela chamada:
|
|
134
|
+
|
|
135
|
+
```ts
|
|
136
|
+
const { data } = await this.http.post(`/orders/${id}/publish`, {}, {
|
|
137
|
+
headers: orfeuHeaders(caller),
|
|
138
|
+
validateStatus: (s) => (s >= 200 && s < 300) || s === 422,
|
|
139
|
+
});
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
- **TLS**: não desligue a verificação (`rejectUnauthorized: false`) no agente HTTP. Se a CA é interna,
|
|
143
|
+
configure `NODE_EXTRA_CA_CERTS`. Proxy de saída só por variável de ambiente e só onde for necessário.
|
|
144
|
+
- Header de trace próprio (`x-trace-id` com `AsyncLocalStorage`) é legado: o trace é o `traceparent` do
|
|
145
|
+
Orfeu. Não crie um segundo mecanismo.
|
|
146
|
+
|
|
147
|
+
## Filtros
|
|
148
|
+
|
|
149
|
+
- Filtros como **argumentos opcionais** do campo (`listOrders(status: String, from: String, to: String)`) ou
|
|
150
|
+
um `input OrderFilters` quando passam de três ou quatro.
|
|
151
|
+
- O resolver/módulo monta `params` só com o que veio preenchido (`null`, `undefined` e `''` não vão).
|
|
152
|
+
- Renomeie para o nome do serviço no módulo (`from` → `from_` quando o Python reserva a palavra).
|
|
153
|
+
- Arrays em query string: o padrão do axios é `key[]=a&key[]=b`; FastAPI espera `key=a&key=b` — use
|
|
154
|
+
`paramsSerializer: { indexes: null }` no `axios.create`.
|
|
155
|
+
- Filtro de **escopo do usuário** (só os itens do time dele) é do serviço de trás, que lê o token — o
|
|
156
|
+
gateway não decide visibilidade.
|
|
157
|
+
|
|
158
|
+
## Paginação
|
|
159
|
+
|
|
160
|
+
Padrão offset/limit, envelope com página:
|
|
161
|
+
|
|
162
|
+
```graphql
|
|
163
|
+
extend type Query {
|
|
164
|
+
"Mais novos primeiro; a tela pede páginas até completar `total`."
|
|
165
|
+
listOrders(filters: OrderFilters, offset: Int, limit: Int): OrdersPageResponse!
|
|
166
|
+
}
|
|
167
|
+
type OrdersPage { items: [Order!]!, total: Int!, offset: Int! }
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
```ts
|
|
171
|
+
listOrders: operation(Level.PRIVATE, (_: unknown, { filters, offset, limit }: ListArgs, ctx: GraphQLContext) =>
|
|
172
|
+
forward(() => ctx.App.Orders.list(filters, offset ?? 0, limit ?? 50, ctx))),
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
Padrão no resolver (`offset ?? 0`, `limit ?? 50`); o teto do `limit` é imposto pelo serviço de trás. Listas
|
|
176
|
+
pequenas (cadastros) podem devolver tudo (`data: [Order!]`) sem página. Cursor não é usado hoje.
|
|
177
|
+
|
|
178
|
+
## Módulos fora do HTTP (subscriptions)
|
|
179
|
+
|
|
180
|
+
Se uma subscription precisa chamar o serviço de trás (ex.: buscar o escopo do usuário), o `ctx.App` precisa
|
|
181
|
+
existir no contexto do WS — passe `App` no `extra` do `orfeuWsContext` (ver
|
|
182
|
+
[estrutura-bootstrap.md](estrutura-bootstrap.md)). Instanciar o módulo à parte, de forma preguiçosa, também
|
|
183
|
+
funciona, mas duplica clientes.
|